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

Uploaded Python 3

File details

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

File metadata

  • Download URL: 3tears_agent_wake-0.24.5.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.5.tar.gz
Algorithm Hash digest
SHA256 77ab13a19dbeeb9409ede6c292caf276861653eb61df88f3e48e23677a84517b
MD5 d363eff271fcc9d098dc9fb5f6fa2fd7
BLAKE2b-256 a50ca2010a165de39e0825e5d56c2f8d1c90dce3b47e0c1792ff5e2ada39a451

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for 3tears_agent_wake-0.24.5-py3-none-any.whl
Algorithm Hash digest
SHA256 53eda5cea064eb607f4dcebabe53e2fac7a461afb54d8847e27a42f4393f3c2c
MD5 d69db553a46d1be3cb832afe4a56c9df
BLAKE2b-256 77b65a63c211b5c5abfd34bfb5b011dfa72bff035f4f69511a671640458e4266

See more details on using hashes here.

Provenance

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

This release

0.24.5 This release

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