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 18, 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 18, 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.26.0.tar.gz (162.8 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.26.0-py3-none-any.whl (113.0 kB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: 3tears_agent_wake-0.26.0.tar.gz
  • Upload date:
  • Size: 162.8 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.26.0.tar.gz
Algorithm Hash digest
SHA256 7d8a536c31f28d4cfc6eb2af774e6b3b74d7ed03d74450d323a81a05608f208d
MD5 ebdccbfaca7124e131b7656bc5473dbc
BLAKE2b-256 1c65228255b0ee153f3f1c39ecbeb4d1967d651ae157d270c91b679f93927776

See more details on using hashes here.

Provenance

The following attestation bundles were made for 3tears_agent_wake-0.26.0.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.26.0-py3-none-any.whl.

File metadata

File hashes

Hashes for 3tears_agent_wake-0.26.0-py3-none-any.whl
Algorithm Hash digest
SHA256 1d8507d1704d1da6255484f814573295456c7d549d7dd38743491789e25edd58
MD5 df6f6b248ffb743690faa72af66e574e
BLAKE2b-256 7858fb0bc970441d486a723b69558255eac1d5471c458c4175088bec6b936d4b

See more details on using hashes here.

Provenance

The following attestation bundles were made for 3tears_agent_wake-0.26.0-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

This release

0.26.0 This release

2 files

0.25.0

2 files

0.24.7

2 files

0.24.6

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