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 13, 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 13, 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.3.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.3-py3-none-any.whl (113.0 kB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: 3tears_agent_wake-0.24.3.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.3.tar.gz
Algorithm Hash digest
SHA256 90ce75c77c22513e8f270e96405017cd6758f840944de6b43f043d19c6d515f5
MD5 301964eb73f9a654601b37fdb50628d7
BLAKE2b-256 fcaf32da030061946a1ebbfc4f2c54ba160c98f236b05ff84a71f62f3f4f18b0

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for 3tears_agent_wake-0.24.3-py3-none-any.whl
Algorithm Hash digest
SHA256 2cda45496ae143da61546f51cdcd57c9d9539f47be9dd7109076148920b5c842
MD5 1cd204abb6bc7f40ff5a7541cdb4e151
BLAKE2b-256 405131e1facc6566fd15548ba9732dc881d7e65e97a7d37bda5f48667e093e10

See more details on using hashes here.

Provenance

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

0.24.6

2 files

0.24.5

2 files

0.24.4

2 files

This release

0.24.3 This release

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