Skip to content

interfaces.md

Latest commit

 

History

History
125 lines (117 loc) · 13.9 KB

interfaces.md

File metadata and controls

125 lines (117 loc) · 13.9 KB
Raw

Interface Boundaries

Keep moving parts explicit and replaceable.

Runtime Interfaces (current)

  • DbClient (src/runtime/db.ts): owns typed Postgres connectivity via Kysely and provides the gravity schema handle.
  • SlackTransport (src/runtime/slack-transport.ts): owns Slack Socket Mode connection, inbound event normalization, and channel-scoped message queueing.
  • defineConfig / defineAgent contracts (agents/contracts.ts): canonical code-defined configuration and agent declaration authoring model.
  • AgentRegistry (agents/index.ts): typed registry assembly with duplicate agentId and slash-command collision guards.
  • CompiledAgentDeclarations (agents/index.ts): code-defined ingress/proactive/session declarations compiled from defineConfig + defineAgent contracts for runtime cutover.
  • SurfaceAdapter: surface-specific ingress/egress adapters (Slack now; additional surfaces later).
  • AgentSpecRepository: transitional repository seam while behavior source moves off gravity.agents.config.
  • EventIdempotencyGuard (src/runtime/event-idempotency.ts): blocks duplicate source events across slash and non-slash ingress paths.
  • SessionKeyBuilder (src/runtime/session-key.ts): canonical builders for mode-dependent session key patterns across slash, message, and proactive entrypoints.
  • SessionResolver: resolves sessionKey and session mode (thread, main, isolated) per trigger.
  • SessionCatalog: stores and resolves session metadata in gravity.sessions (ownership, mode, status) while keeping full transcript/context in workspace/ files, including explicit close transitions for idle/shutdown hooks and guarded stale-callback close checks (closeSessionIfUnchanged).
  • ResourcePlugin (src/resources/types.ts): typed resource interface (load(...)) with discriminated resource specs and compile-time contribution contracts.
  • ResourceRegistry (src/resources/registry.ts): statically maps all resource kinds to plugins with exhaustive compile-time coverage checks and resolves per-turn resource contributions.
  • CapabilityCatalog (agents/capability-catalog.ts): canonical catalog of capability definitions (resourceSlots, skills, and tool grants).
  • CapabilityBindingContract (agents/contracts.ts): typed useCapabilities[] + bindResources agent contract with compile-time slot/resource-kind checks.
  • CapabilityCompiler (agents/capability-compiler.ts): compiles capability bindings into per-agent runtime capability profile (required skills/resources + tool grants).
  • SkillResolver (src/runtime/context-assembler.ts): resolves capability-derived shared skill IDs to shared skill markdown each turn (no caching).
  • MemoryStore: loads/writes MEMORY.md per agent.
  • ContextAssembler (src/runtime/context-assembler.ts): builds per-turn system context from compiled capability profile + memory + resource contributions.
  • SessionHistoryStore (src/runtime/session-history-store.ts): owns dual-history file contract (log.jsonl, context.jsonl, agent-log.jsonl) and pre-run log-to-context sync with source-event dedupe markers plus explicit replay-exclusion metadata (skipContextReplay).
  • SlackThreadHistory (src/runtime/slack-thread-history.ts): shared thread-message contract used by Slack transport and startup backfill seams.
  • SessionStartupBackfill (src/runtime/session-startup-backfill.ts): startup seam that reconciles active Slack thread sessions and appends missed thread messages into session logs before runs.
  • SessionOverflowRecovery (src/runtime/session-overflow-recovery.ts): fail-safe helper that compacts and retries once when prompt execution throws context-overflow errors.
  • SessionIdleEvictionCoordinator (src/runtime/session-idle-eviction.ts): idle timer + callback orchestrator that triggers session-end close flows (idle_eviction and shutdown).
  • SessionEndMemoryHook (src/runtime/session-end-memory-hook.ts): silent memory-write hook that runs a final model turn on idle close, appends hook input/output records to session log, and enforces skip guards (missing_api_key, missing_memory_path).
  • TurnRunner (PiAgentRunner for CP4/CP6): executes one model turn via pi-coding-agent, applies pre-run sync, compaction/retry settings, and overflow recovery.
  • DeliveryAdapter: posts acknowledgements/final responses using surface-specific delivery defaults.
  • SessionStore: implemented through SessionHistoryStore and SessionManager for per-session log.jsonl and context.jsonl lifecycle.
  • RunLifecycleLogger (src/runtime/run-lifecycle.ts): emits typed run lifecycle events with stable IDs (runId, agentId, sessionKey) and lifecycle stages (started, completed, failed).
  • RunLogStore (src/runtime/run-log-store.ts): maps lifecycle stages into durable gravity.runs inserts/updates.
  • ExecutorManager (src/runtime/executor-manager.ts): single executor dispatch seam for all tool execution with per-agent runtime selection, fail-closed sandbox policy decisions (allow/deny + reason), and force-host fail-closed mode (GRAVITY_SANDBOX_FORCE_HOST denies sandbox-declared runs).
  • ToolDispatcher: single dispatch seam for all tool execution (implemented through ExecutorManager in current runtime).
  • ProactiveTriggerScheduler (src/runtime/proactive-trigger-scheduler.ts): runs cron/heartbeat triggers, replays missed proactive runs from persisted history, enforces quiet-hours suppression, and exposes manual wake control for heartbeat demo triggers.

CP8 Self-Authoring Interfaces (current)

  • SelfAuthoringIntentDetector (src/runtime/self-authoring-intent.ts): detects teach/update intent and generates the single-turn structured mutation payload used by CP8 mutation transactions.
  • SelfAuthoringTypes (src/runtime/self-authoring-types.ts): shared CP8 transaction types for mutation payloads and stable-ID request context across coordinator, queue, policy, and applier seams.
  • SelfAuthoringMutationCoordinator (src/runtime/self-authoring-mutation-coordinator.ts): orchestrates one self-authoring mutation transaction (request -> authoring turn -> lock -> apply -> audit) for a target agent/session context.
  • SelfAuthoringMutationQueue (src/runtime/self-authoring-mutation-queue.ts): enforces per-agent conflict serialization with FIFO queueing for concurrent self-author requests plus trigger-key dedupe.
  • SelfAuthoringMutationPolicy (src/runtime/self-authoring-mutation-policy.ts): validates proposed mutation targets against CP8 allowlist policy (skills + agent memory only) and rejects all non-allowlisted paths fail-closed.
  • SelfAuthoringMutationApplier (src/runtime/self-authoring-mutation-applier.ts): applies approved self-authored skill/memory deltas to durable stores (store/shared/skills, store/agents/{agentId}/memory/MEMORY.md) with explicit write boundaries.
  • SkillVersionAuditStore (src/runtime/skill-version-audit-store.ts): records self-authored skill evolution metadata in gravity.skill_versions with stable-ID linkage to request/run context.

CP9 Pearlboy Interfaces (current)

  • PiAgentRunner (src/runtime/pi-agent-runner.ts): executes Pearlboy turns using the same conversational runtime path as other agents.
  • Compliance Guidance Skills (store/shared/skills/compliance-helper-review-rules.md, store/shared/skills/compliance-helper-flag-patterns.md): shared policy guidance surfaced in prompt context for conversational review and follow-up Q&A.

Removed Legacy Seams (CP5.1 Step 6)

  • src/runtime/agent-config.ts
  • src/runtime/ingress-binding-resolver.ts
  • src/runtime/proactive-trigger-resolver.ts
  • src/runtime/slash-command-router.ts
  • src/runtime/trigger-normalizer.ts

Non-Goals for Current Bootstrap

  • No full multi-surface adapter set beyond Slack yet.
  • No full multi-surface ingress matrix beyond Slack entrypoints yet.
  • No full sandbox approval-state workflow yet (request_id, timeout, cancel, pending states; TD-008).

Ownership and Rollback Notes

  • Legacy seam rollback: removed CP5.1 seams are restored only via revision revert.
  • DbClient owner: platform runtime layer.
  • DbClient rollback path: swap src/runtime/db.ts back to direct pg access while preserving SQL contracts and migration files.
  • SlackTransport owner: platform runtime layer.
  • SlackTransport rollback path: disable live Slack connection in src/index.ts and fall back to no-op inbound logging while preserving normalized inbound event contracts.
  • defineConfig / defineAgent contracts owner: platform runtime layer.
  • defineConfig / defineAgent rollback path: revert agents/contracts.ts to previous declaration shape while preserving required IDs (agentId, sessionKey, runId) in downstream runtime contracts.
  • AgentRegistry owner: platform runtime layer.
  • AgentRegistry rollback path: pin agents/index.ts to previous known-good declarations and keep DB projection unchanged.
  • EventIdempotencyGuard owner: platform runtime layer.
  • EventIdempotencyGuard rollback path: disable runtime pre-run duplicate checks and rely on gravity.runs.source_event_id uniqueness only.
  • SessionKeyBuilder owner: platform runtime layer.
  • SessionKeyBuilder rollback path: revert session-key builders to previous deterministic patterns while preserving DB session metadata and stable IDs.
  • AgentSpecRepository owner: platform runtime layer.
  • AgentSpecRepository rollback path: read minimal agent fields directly from gravity.agents and ignore advanced config blocks.
  • SessionResolver owner: platform runtime layer.
  • SessionResolver rollback path: revert to deterministic sessionKey = {agentId}:{sourceEventId} behavior.
  • SessionCatalog owner: platform runtime layer.
  • SessionCatalog rollback path: resolve sessions from workspace/ path conventions only while preserving gravity.sessions schema for forward compatibility.
  • SessionHistoryStore owner: platform runtime layer.
  • SessionHistoryStore rollback path: bypass log/context sync hooks and write only context.jsonl through SessionManager while preserving workspace path conventions.
  • SessionStartupBackfill owner: platform runtime layer.
  • SessionStartupBackfill rollback path: disable startup reconciliation and rely on live inbound events + pre-run sync only.
  • SessionOverflowRecovery owner: platform runtime layer.
  • SessionOverflowRecovery rollback path: delegate overflow handling to default pi-coding-agent behavior with no explicit post-error compact/retry wrapper.
  • SessionIdleEvictionCoordinator owner: platform runtime layer.
  • SessionIdleEvictionCoordinator rollback path: disable idle timers and keep sessions active until process shutdown while preserving gravity.sessions schema.
  • SessionEndMemoryHook owner: platform runtime layer.
  • SessionEndMemoryHook rollback path: disable GRAVITY_SESSION_MEMORY_HOOK_ENABLED and retain session close transitions without silent memory-write turns.
  • ResourceRegistry owner: platform runtime layer.
  • ResourceRegistry rollback path: hardcode a single resource path per agent in runtime code while preserving agent config columns.
  • CapabilityCompiler owner: platform runtime layer.
  • CapabilityCompiler rollback path: inline capability expansion in runner/context code while preserving capability declarations in agents/contracts.ts.
  • SkillResolver owner: platform runtime layer.
  • SkillResolver rollback path: revert context assembly to direct shared skill loading while preserving capability-derived skill IDs.
  • ContextAssembler owner: platform runtime layer.
  • ContextAssembler rollback path: inline context assembly in runner code while preserving per-turn reload semantics.
  • RunLifecycleLogger owner: platform runtime layer.
  • RunLifecycleLogger rollback path: revert runtime entrypoints to direct console.log messages while preserving stable ID fields in log lines.
  • RunLogStore owner: platform runtime layer.
  • RunLogStore rollback path: keep lifecycle log lines but disable gravity.runs writes from src/index.ts while retaining the DB schema contract.
  • ExecutorManager owner: platform runtime layer.
  • ExecutorManager rollback path: block sandbox-declared runs by setting GRAVITY_SANDBOX_FORCE_HOST=true (or GRAVITY_SANDBOX_ENABLED=false) while keeping runtime policy fields backward-compatible.
  • ProactiveTriggerScheduler owner: platform runtime layer.
  • ProactiveTriggerScheduler rollback path: disable scheduler startup and replay/wake control surfaces while preserving proactiveTriggers config contracts.
  • SelfAuthoringMutationCoordinator owner: platform runtime layer.
  • SelfAuthoringMutationCoordinator rollback path: disable autonomous mutation orchestration and require explicit operator/manual mutation flow while preserving gravity.runs logging contracts.
  • SelfAuthoringMutationQueue owner: platform runtime layer.
  • SelfAuthoringMutationQueue rollback path: disable queueing and execute only when mutation lock is immediately available, with explicit busy-reject responses for conflicts.
  • SelfAuthoringMutationPolicy owner: platform runtime layer.
  • SelfAuthoringMutationPolicy rollback path: disable autonomous mutation policy checks and force manual operator approval for all mutation writes until allowlist enforcement is restored.
  • SelfAuthoringMutationApplier owner: platform runtime layer.
  • SelfAuthoringMutationApplier rollback path: disable autonomous skill/memory writes and require manual operator-authored file updates while preserving request/run lifecycle logging.
  • SkillVersionAuditStore owner: platform runtime layer.
  • SkillVersionAuditStore rollback path: disable gravity.skill_versions writes and rely on file history-only audit until DB audit path is restored.
  • PiAgentRunner owner: platform runtime layer.
  • PiAgentRunner rollback path: revert inbound execution paths to deterministic echo-only behavior while preserving RunLifecycleLogger + RunLogStore contracts.

Stability Requirement

Do not change interface boundaries without updating this file and docs/checkpoints/mvp-status.md in the same change.