PaperClipAI/doc/plugins/AGENT_RUNTIME_SYNC.md

Agent runtime synchronization

Plugins can opt into committed agent runtime changes with resourceLifecycle: ["agent_runtime"] and events.subscribe. Implement onResourceLifecycle and handle update and delete. Existing agent and project subscriptions do not receive this new resource type. Manual inbox reads retain both legacy streams regardless of automatic subscriptions. They include runtime events only when the manifest opts into agent_runtime.

An event contains company identity, agent identity in resourceId, a numeric sequence serialized as id, and its action. It contains no file contents, configuration, or credentials. Treat id as an opaque decimal revision, not a JavaScript floating-point value. Delivery is at least once and ordered per agent. Return acknowledged only after external effects finish. Return retry after an unfinished operation, or deferred when configuration is missing. Startup, plugin startup, and configuration changes recover unacknowledged work.

The host records configuration changes at the database mutation boundary. This covers API saves, rollback, plugin writes, and background writers. No-op updates and heartbeat accounting do not create runtime work. Instruction edits, file deletions, restores, and run writeback use the file audit boundary. Pending hires produce no update until approval. Returning to the ready lifecycle phase requests synchronization after preparation or resume. Existing agents receive a one-time baseline when the migration runs. Agent deletion leaves a durable delete event.

PostgreSQL notifications wake the existing durable dispatcher only after commit, including writes through independent clients. Notifications carry no identifiers or contents. The journal remains authoritative. The listener scans on connection and reconnection so a dropped notification does not lose committed work. There is no recurring empty-inbox poll. Existing retry deadlines still retry failed work. A process opens one listener connection only after a ready plugin opts into agent_runtime. The database connection must support session-level LISTEN; transaction-mode poolers are not supported for this opt-in feature. Startup waits for listener registration. It releases the listener after the last runtime subscriber is disabled or removed. Legacy subscriptions keep process-local work signals.

A plugin that also has agents.lifecycle.manage can call ctx.agents.getRuntime(agentId, companyId) from a company-scoped invocation. Only the enabled, ready plugin selected in that agent's required lifecycle set can read these inputs. The result supplies the latest runtime revision, the normalized agent configuration, instruction root and entry filename, and that plugin's own instance secrets. Instruction paths use the same managed-folder recovery as the instruction reader. A missing or cross-company agent returns null. The instruction root identifies host files that the trusted worker can package through its existing filesystem access. This API grants no arbitrary path reads. Never expose instance secrets through UI data, logs, plugin state, or agent files.

Use ctx.agents.getRuntimeIdentity(agentId, companyId) for freshness checks. It returns only the revision, agent ID, company ID, status, lifecycle state and version, and this plugin's current instance secrets. It uses the same ownership, capability, and company checks as getRuntime. Each call reads current state; it does not cache grants or secrets. It does not resolve instruction files, company reporting relationships, skills, or connection assignments. Read the full runtime once to obtain synchronization inputs, then use the identity reader to fence effects against changes.

Re-read current state before external effects. A queued event can be older than the returned revision. Fence stale revisions at the destination and use its conditional writes. Current configuration is desired state, not a frozen run snapshot or permission to change an active provider session. Execution admission and provider activation keep their existing checks. The private transport consumer is a separate integration.

Filesystem changes outside Paperclip's managed write APIs do not emit these hooks. Filesystem publication and the database journal are not one filesystem transaction. A failed managed write must be repaired through the same API before claiming synchronization. Upstream repository detection remains owned by the source integration.

Successful file saves record the current desired state. Identical retries and already-applied deletions repair a missing journal event if a prior save published bytes before its database transaction failed. Audit rows carry their runtime revision, so repeated identical saves against that revision create no audit rows or events. Later runtime changes invalidate that deduplication. The file API still returns changed: false for identical content and keeps conditional-write checks. Consumers can skip rewriting content whose hash already matches.

Skills

Migration 0348 invalidates referencing agents when installed skill content, companion files, versions, source bindings, or identities change. Rename checks both old and new keys. String selections, structured selections, and supported legacy aliases are recognized. Unrelated agents and other companies receive no content invalidation. Private-source bindings, membership, and privacy changes invalidate only agents assigned skills from the affected sources. Project workspace authorization-policy changes use the same boundary. Company policy changes conservatively invalidate the company. Source retry/lease bookkeeping and skill popularity counters do not emit changes. Multi-skill source publication defers its skill invalidation until transaction commit, after it acquires all skill rows. This avoids an agent-lock/skill-lock cycle with concurrent version saves. Individual file edits retain immediate journaling and their existing filesystem rollback behavior.

Assignment edits already use the configuration boundary. The runtime reader returns selected skill entries with host source paths and immutable version IDs. It uses the execution resolver, current agent access, the instance pin flag, and legacy operational-skill rules. It performs no upstream refresh. The resolver can rebuild an expired version cache from saved bytes. Slow materialization happens outside the agent row lock. The reader rechecks ownership and revision afterward; it retries concurrent changes three times and then returns a conflict.

Pinned assignments receive conservative content invalidations too. Their resolved version and bytes stay pinned when pin support is enabled. Consumers can compare versions or destination hashes and avoid rewriting unchanged trees. Task-only skill mentions and a running task's saved version selection remain task-owned.

Standing connection assignments

getRuntime also returns connectionAssignments: effective publicMcp and chatConnectors feature switches, installed connections with id, name, transport, enabled, and status, and active profile IDs. It includes both company assignments and assignments for the requested agent. It excludes other agents' assignments and has no credential values, grant details, or tool schemas. The owning-plugin checks for the runtime reader apply to this field too.

Migration 0354 records committed changes to every stored field used by this snapshot. Agent-targeted installation and profile binding edits invalidate only their old and new target agents. Company-targeted assignments invalidate company agent runtimes. Project, routine, issue, and gateway bindings are outside this snapshot and do not invalidate it. Connection metadata, profile activation or removal, and connector feature switches still use conservative company-wide invalidation. Empty writes and changes to health bookkeeping do not. Multiple assignment statements in one transaction coalesce to one update per agent. Journal writes and their triggering changes commit or roll back together. Company-wide invalidation remains synchronous: it locks eligible company agents in order and journals one update per agent. Its work grows with company size; there is no fanout ceiling or cross-transaction mutation quota.

The reader orders and deduplicates assignments. It rejects more than 512 connections or 128 active profiles with status 422 instead of returning a partial snapshot. It rechecks the revision after reading assignments and skills, with the same three-attempt conflict behavior described above.

Each delivery-service startup records one company baseline when an enabled runtime subscriber becomes active. This covers feature overlays supplied at process startup. It does not add a recurring scan. Plugins must compare desired state and destination hashes before rewriting external files.

Standing assignments express desired state; they do not prove task-specific authorization. Existing agent and skill invalidations still apply independently.

Tool definitions and configuration

Migration 0355 extends runtime invalidation to application and connection configuration, catalog contents, profile entries, policies, and MCP gateways. These changes use the same content-free journal, atomic commit behavior, and transaction coalescing. Bulk discovery invalidates once per company per committed chunk instead of once per tool. Unchanged rediscovery, health bookkeeping, and trust-rule usage counters do not request preparation. Binding and installation notifications retain the scoped recipients described above. Profile-entry changes notify agents from the old and new profiles' standing bindings. Policies use their old and new agentId and agentIds selectors, including their intersection when both are set. Unscoped policies and company-bound profiles retain atomic company fanout. Other definition changes still use conservative company-wide fanout with the same documented company-size cost.

Profile entry mutations lock referenced applications, connections, and catalog rows before the parent profile. They then change the entries and parent in one transaction, using the reserved connection for validation and profile reads. Profile replacement locks both old and new references before the parent. It rechecks the reference set under the parent lock and retries up to three times if a concurrent entry edit changes it. Continued churn returns a conflict. Setup finalization and catalog publication can run concurrently without acquiring these locks in the opposite order. Policy reorder locks all affected policies in ID order and changes their priorities in one statement so scoped agent locks are ordered across the set. Connection removal locks the managed profile before deleting its entries in the same transaction.

The bounded assignment snapshot remains the API described above. An invalidation can advance its revision without changing its assignment fields. Consumers must use their existing authorized readers for tool definitions and configuration.

Access, credentials, and endpoints

Migration 0356 adds connection grants, grant audiences and delegations, company membership and permissions, secret bindings, chat/email endpoint configuration, and referenced credential rotation or revocation. Vault configuration and status changes invalidate companies whose connector credentials reference that vault. Vault health checks, OAuth grant refresh leases, Vercel verification timestamps, GitHub webhook health, and endpoint publication timestamps do not request work. Credential identifiers, expiry, and repository access changes remain covered. Events contain no credential values, phone numbers, or provider payloads.

Access changes conservatively invalidate eligible company agents because responsible-user and task-time access can vary across runs. Agent secret bindings instead invalidate their owning agent. Personal delegation creation, reassignment, and revocation invalidate only their old and new target agents. Whole-grant revocation and membership cleanup retain company invalidation. Unchanged grant audiences preserve their rows after membership validation.

OAuth persistence and membership cleanup lock affected grants before connection inputs and credential mutations. Each affected set is locked in ID order. Task completion locks existing grants before assignment inputs. Permission-only saves lock membership before replacing permissions, as role and status saves do. Slack search refresh, callbacks, and disconnect lock only the subject's grants before their connection. After locking the connection, they recheck the grants without waiting. A newly discovered busy grant rolls back and retries before provider work or credential persistence. Three failed attempts return a retryable conflict. Each operation adds two grant queries, bounded to the subject and connection. The existing connection lock still serializes provider refresh work.

Membership cleanup locks credential deletion candidates without waiting before company agent locks. A busy credential rolls back the complete membership transaction, including its membership and grant locks. All four cleanup entry points re-read their state on retry, with at most three attempts. Company-access changes process companies in ID order.

Personal delegation creation locks its grant, connection reference, and target agent before insertion. Delegation revocation locks its grant and target before deletion. Whole-grant and membership cleanup lock eligible company agents in ID order before deleting scoped delegations. Static-key reconnect locks grants and connection inputs before credential writes. Secret removal locks company agents in ID order before cascading into bindings. Plugin instance secrets cannot use ordinary bindings, so their removal retains its owner lock without a company sweep. It tries the secret lock without waiting, releases its transaction locks if that lock is busy, and retries up to three times. Continued contention returns a retryable conflict. Provider deletion stays outside that transaction; retrying resumes removal of the already disabled secret. These guards accompany the hooks that require them.

The runtime snapshot still excludes credentials and arbitrary configuration. Task-scoped profile bindings, responsible-user consent, gateway sessions, automatic connector skill overlays, and connection instructions remain in the existing run preparation path. Invalidation does not create a run identity or activate a provider session. Transport consumers must preserve those boundaries.