3tears-agent-wake

Long-running-agent foundation for 3tears-based agents. This package ships the schema + Collection layer for three platform tables:

  • agent_wake_schedules -- one row per active wake schedule for a conversation (cron / one-shot / random-window / etc). Carries a nullable skill_id FK referencing the cross-package agent_skills.skill_id standalone UNIQUE.
  • wake_fires -- one row per wake fire (history; status enum spans 'fired', 'fired_silent', 'yielded', 'skipped_busy', 'skipped_rate_limit', 'skipped_cap', 'skipped_no_handler', 'failed').
  • webhook_subscriptions -- one row per inbound HTTP webhook subscription. Carries nullable default_skill_id FK to agent_skills.skill_id and Fernet-encrypted secret_ciphertext.

Plus three BaseEntity subclasses, three BaseCollection subclasses, and an agent-scope migration registration declaring depends_on=("conversations", "agent_skills").

No tick engine, no dispatch handler, no agent tools, and no Pydantic API models live in this package.

Partitioning

All three tables partition by conversation_id (wake operations are conversation-scoped). The Collections expose partition_column = "conversation_id" so the workspace partition-column enforcement walker audits every SQL string touching these tables for the predicate.

There is intentionally NO database-level FK on conversation_id -> conversations(conversation_id). The 3tears conversations table carries a composite PK (agent_id, conversation_id) and no standalone UNIQUE (conversation_id) constraint, so a single-column FK is not legal. The same precedent applies in packages/agent/tools/ (context_items.conversation_id) and packages/agent/skills/ (agent_skill_invocations.conversation_id). Conversation lifecycle is governed by app-level cascade through ConversationsCollection.

Orphan-row implication. Because there is no DB-level FK, deleting a row from conversations does NOT automatically remove the wake schedules, fires, or webhook subscriptions for that conversation. They become orphans (rows whose conversation_id no longer resolves). The partition-column enforcement walker keeps the application blind to orphans (every query is filtered by conversation_id so an orphan is invisible at the read path), but the rows still occupy storage. This is the same trade-off agent-tools and agent-skills make. A future cross-package cleanup (a TRIGGER on conversations-delete that fans out to dependent tables, or a periodic GC job in ConversationsCollection) would close the gap; that work is intentionally cross-cutting and out of scope for this package.

Migration registration

from threetears.agent.wake import register as register_wake
from threetears.core.data.migrations import MigrationRunner

runner = MigrationRunner()
register_wake(runner)

Migrations are agent-scoped and declare depends_on=("conversations", "agent_skills") -- the canonical MigrationRunner topologically orders the agent-scope pass so the conversations + agent_skills migrations apply before any wake table is created.

Design references

See docs/agent-wake/README.md for the package overview and the locked design decisions.

Project links

Data verified by PyPI on Aug 17, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.27.0)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for pace from gravatar.com pace

Credits

Author: pace

GitHub Statistics

Data verified by PyPI on Aug 17, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

MIT
View SPDX License List

Requires

Python >=3.14

Provides Extra

prometheus

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

3tears_agent_wake-0.24.6.tar.gz (162.6 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

3tears_agent_wake-0.24.6-py3-none-any.whl (113.0 kB view details)

Uploaded Python 3

File details

Details for the file 3tears_agent_wake-0.24.6.tar.gz.

File metadata

  • Download URL: 3tears_agent_wake-0.24.6.tar.gz
  • Upload date:
  • Size: 162.6 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for 3tears_agent_wake-0.24.6.tar.gz
Algorithm Hash digest
SHA256 ddcba7ec7988bb579c822bfbf831d2915226380dfa8c96ba18bf2ef80261998b
MD5 7c3dcf1d512c832ea2f5cd5713ae5666
BLAKE2b-256 9f0974f0c9a5ecab0936ecc4bdfba601f3272d04854417d734bd3ededdb235d2

See more details on using hashes here.

Provenance

The following attestation bundles were made for 3tears_agent_wake-0.24.6.tar.gz:

Publisher: release.yml on pacepace/3tears

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file 3tears_agent_wake-0.24.6-py3-none-any.whl.

File metadata

File hashes

Hashes for 3tears_agent_wake-0.24.6-py3-none-any.whl
Algorithm Hash digest
SHA256 2501575d690ef7f05752f603fb24eb37fe85418e6136d259f9af3d4f877b2bf3
MD5 f9504803565dd69617e3fb6b80e6342c
BLAKE2b-256 3e11e858a2bae111ad8b1e6703990e37a8e034937338000dc0ff726dea6dc166

See more details on using hashes here.

Provenance

The following attestation bundles were made for 3tears_agent_wake-0.24.6-py3-none-any.whl:

Publisher: release.yml on pacepace/3tears

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

0.27.0

2 files

0.26.1

2 files

0.26.0

2 files

0.25.0

2 files

0.24.7

2 files

This release

0.24.6 This release

2 files

0.24.5

2 files

0.24.4

2 files

0.24.3

2 files

0.24.2

2 files

0.24.1

2 files

0.24.0

2 files

0.23.11

2 files

0.23.10

2 files

0.23.9

2 files

0.23.8

2 files

0.23.7

2 files

0.23.6

2 files

0.23.5

2 files

0.23.3

2 files

0.23.2

2 files

0.23.1

2 files

0.23.0

2 files

0.22.5

2 files

0.22.4

2 files

0.22.3

2 files

0.22.2

2 files

0.22.1

2 files

0.22.0

2 files

0.21.0

2 files

0.20.0

2 files

0.19.4

2 files

0.19.3

2 files

0.19.2

2 files

0.19.1

2 files

0.19.0

2 files

0.18.0

2 files

0.17.9

2 files

0.17.8

2 files

0.17.7

2 files

0.17.6

2 files

0.17.5

2 files

0.17.4

2 files

0.17.3

2 files

0.17.2

2 files

0.17.1

2 files

0.17.0

2 files

0.16.1

2 files

0.16.0

2 files

0.15.0

2 files

0.14.1

2 files

0.14.0

2 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page