Merged
Conversation
…ffold Introduce code-defined authoring primitives for CP5.1 with explicit contract normalization and validation. What changed: - Added defineConfig/defineAgent contract layer in agents/contracts.ts with normalization, strict required-field validation, quiet-hours/delivery/session helpers, and resolution-order utilities. - Added code-defined declarations for existing agents in agents/data-analyst/agent.ts and agents/compliance-helper/agent.ts. - Added typed registry assembly in agents/index.ts with duplicate agent-id guardrails and slash-command collision detection, plus runtime config baseline. - Added focused unit coverage for contracts and registry behavior in tests/agents/contracts.test.ts and tests/agents/index.test.ts. - Updated CP5.1 plan/checkpoint/interface docs to record Step 1 completion evidence and current cutover boundary. - Updated tsconfig include/root and package start script for emitted build layout with top-level agents source. Verification: - npm run check - npm run build
Implement the CP5.1 declaration compile layer in agents/index.ts and validate it with targeted tests. What changed: - Added CompiledAgentDeclarations output with typed ingress listeners, proactive triggers, session dimensions, and trigger dimensions. - Added explicit trigger dimension contracts for triggerKind/surface/entrypoint plus runId pattern to keep runtime identity rules explicit. - Added session-key pattern dimensions for ingress/proactive modes to make session contract expectations explicit before runtime cutover. - Added proactive compilation guardrails: duplicate trigger-id detection per agent and fail-closed behavior when delivery cannot be resolved. - Preserved existing registry API while extending it with compiledDeclarations and a convenience export. - Expanded tests/agents/index.test.ts to cover compiled declaration outputs and proactive/session dimension behavior. - Updated CP5.1 plan + checkpoint + interfaces docs to mark Step 2 complete and reflect current boundary (compile complete, cutover pending). Verification: - npm run check
…ions Rewire slash and non-slash message routing in src/index.ts to use code-compiled declarations from agents/index.ts instead of DB JSONB resolver paths. What changed: - Replaced slash command agent resolution with compiledDeclarations.ingress.slashCommands lookup. - Replaced app_mention/thread_reply/direct_message ingress resolution with compiled declaration listener matching in src/index.ts. - Preserved existing runtime behavior contracts: active-agent filtering via DB status, channel-affinity tie-break, thread-owner matching, ack behavior, and run/session lifecycle persistence. - Switched slash/message trigger dimensions at ingress boundaries to compiled declaration dimensions (no normalizeSlackSlashCommandTrigger/normalizeSlackMessageTrigger calls). - Updated CP5.1 plan/checkpoint/interfaces docs to mark Step 3 complete and capture current boundary (proactive cutover pending). Verification: - npm run check
Move proactive trigger loading off JSONB config resolution in runtime path and lock canonical session-key patterns across ingress/proactive entrypoints. What changed: - Added scheduler loadTriggers seam in src/runtime/proactive-trigger-scheduler.ts and kept JSONB loader as compatibility fallback. - Wired src/index.ts scheduler startup to load proactive triggers from compiledDeclarations.proactive filtered by active DB agents, preserving status-based activation semantics. - Switched proactive trigger dimensions at ingress boundary to scheduler-emitted trigger metadata (event.trigger) rather than trigger-normalizer helper calls. - Added canonical session-key builders in src/runtime/session-key.ts and migrated src/index.ts slash/message/proactive key construction to use them. - Updated slash thread session binding to use thread-key pattern after root thread creation; manual wake uses isolated session key. - Added tests/runtime/session-key.test.ts to validate canonical key patterns across main/thread/isolated + DM thread fallback and proactive modes. - Updated CP5.1 plan/checkpoint/interfaces docs to mark Step 4 complete and reflect proactive/runtime cutover boundary. Verification: - npm run check
Introduce a single executor dispatch seam with per-agent runtime selection and wire tool binding through it end-to-end. What changed: - Added src/runtime/executor-manager.ts to resolve runtime policy to an Executor and construct tools through one seam. - Implemented host executor as default and sandbox scaffold as disabled/fail-closed policy for CP5.1. - Updated src/runtime/pi-agent-runner.ts to receive executorManager + agentRuntime and bind tools via executor.createTools(). - Updated src/index.ts to resolve per-agent runtime from agentRegistry declarations and pass executor policy into runPiAgentTurn. - Added tests/runtime/executor-manager.test.ts coverage for host resolution and sandbox fail-closed/scaffold behavior. - Updated CP5.1 plan/checkpoint/interfaces docs to mark Step 5 complete and document the new runtime boundary. Verification: - npm run test:unit - npm run check
Delete the five JSONB-driven runtime seam modules and their unit tests now that runtime behavior has been cut over to compiled declarations and typed trigger/session dimensions. Runtime rewires: - proactive scheduler no longer has implicit JSONB fallback; loadTriggers is now required and trigger/quiet-hours types are owned by scheduler - index runtime consumes scheduler-emitted proactive trigger dimensions directly and inlines system bootstrap trigger dimensions - slash command normalization now has a single canonical helper exported from slack-transport - pi-agent-runner now sources canonical model/connector/duckdb metadata from the code-defined agent registry and limits DB reads to active-agent + path fields Contract and harness updates: - add optional duckdbPath to defineAgent contract and set data-analyst declaration duckdbPath - migrate verify-cp10 harness to inject typed proactive declarations via scheduler.loadTriggers instead of mutating agents.config JSONB Documentation updates: - update CP5.1 active plan status: Step 6 complete, Step 7 next - update architecture interfaces to record removed legacy seams - update MVP checkpoint board to reflect Step 6 completion and Step 7 parity/doc closeout remaining Validation: - npm run check
Complete CP5.1 Step 7 by recording parity verification evidence, closing checkpoint state, and transitioning planning artifacts to the next active checkpoint. Plan transitions: - move CP5.1 plan to docs/plans/completed and mark overall plan + Step 7 status complete - move CP6 plan from on-hold to active and replace hold reason with explicit resume context/evidence Checkpoint/docs updates: - mark CP5.1 complete in MVP status with parity gate evidence - mark CP6 in progress (unblocked) and set CP6 execution as next milestone - repoint docs index and AGENTS fast map current execution plan link to active CP6 plan Verification run before closeout: - npm run verify:cp5 - npm run verify:cp10 - npm run check - npm run lint:repo
…kdbPath path Refactor defineAgent connector modeling so connector-specific settings live only inside connector declarations. Contract changes: - replace string connectors with typed connector union (duckdb + knowledge-docs) - require DuckDB path inside duckdb connector object - remove top-level duckdbPath from AgentDefinition input/output - enforce duplicate-connector-type rejection during normalization - add fail-closed migration guard that throws if deprecated duckdbPath is provided Runtime changes: - pi-agent-runner now consumes connector objects directly from code-defined declarations - derive duckdb connector path from connector object only (no flattened path flow) - load shared connector docs by declared connector types Declaration and test updates: - migrate built-in agents to connector-object declarations - update contracts tests for new connector shape and add deprecated duckdbPath rejection coverage Docs update: - clarify in rearchitecture decision that connector-specific settings must be nested in connectors and top-level connector fields are not allowed Validation: - npm run check
… follow-ups Fix inbound message entrypoint resolution for Slack DMs by prioritizing direct_message before thread_reply. Why: users can start Slack thread UI off bot messages in DM channels; those replies may not have a thread-owned session binding and were being dropped as unmapped/ignored. Behavior change: - all DM inbound messages (including thread replies) route through direct_message listeners - channel thread_reply behavior in non-DM channels is unchanged Validation: - npm run check
Context
- Continue the post-CP5.1 rearchitecture by replacing legacy tools/connectors
contracts with explicit capabilities + bound resources.
- Keep runtime behavior, verification harnesses, and architecture docs in sync
while CP6 session/memory scaffolding begins.
Agent contracts and capability model
- Add `agents/capability-catalog.ts` as the canonical capability map with
resource slots, required shared skills, tool primitive grants, and guidance.
Included capability IDs:
- `query-gravity-v1`
- `rollback-v1`
- `duckdb-analyst-v1`
- `knowledge-docs-review-v1`
- Add `agents/resource-kinds.ts` and `agents/tool-primitives.ts` to define
typed unions used across contracts/runtime.
- Add `agents/capability-compiler.ts` to compile `useCapabilities[]` bindings
into an execution profile:
- required shared skill IDs
- bound/required resources
- granted tool primitives
- guidance lines with concrete slot->resource bindings
- Rework `defineAgent(...)` in `agents/contracts.ts` to use:
- `resources[]` (typed resource declarations)
- `useCapabilities[]` (capability IDs + `bindResources`)
and remove legacy contract surface (`duckdbPath`, `connectors`,
`capabilities`, `tools`, `skills`) with explicit fail-closed errors.
- Add strong capability/resource validation:
- compile-time checks for slot coverage + resource-kind correctness
- runtime checks for missing/unknown resource IDs, invalid slots,
duplicate binding signatures, and duplicate resource IDs.
- Add `agents/contracts.typecheck.ts` to lock compile-time binding guarantees.
- Update concrete agents (`data-analyst`, `compliance-helper`) to declare
resources and capability bindings.
- Extend `agents/index.ts` registry entries with compiled capability profiles
and treat `quietHours.enabled=false` as no active quiet-hours window.
Runtime and context assembly changes
- Add typed resource plugin system under `src/resources/`:
- `types.ts` resource/plugin contracts
- `registry.ts` exhaustive resource-kind dispatcher
- `duckdb/plugin.ts` shared doc loading + dbt metadata context loading
- `knowledge-docs/plugin.ts` shared policy-doc loading
- `fs-utils.ts` reusable markdown/path/file helpers
- Add `src/runtime/context-assembler.ts` to centralize per-turn context build:
- prompt normalization with resource-aware fallback messaging
- shared-skill loading from capability-derived skill IDs
- resource guidance/docs/context injection
- memory loading from `MEMORY.md`
- capability guidance + operating expectations composition
- Refactor `src/runtime/pi-agent-runner.ts` to consume assembled context and
compiled capability profiles instead of inlined connector/skill loaders.
- Enforce tool access from capability grants only:
- `Executor.createTools(cwd, allowedToolPrimitives)` now filters tool surface
- run fails closed when an agent has zero granted primitives
- Keep session context path aligned with configured workspace root.
- Update `src/runtime/config.ts` to read env vars through `runtimeConfig`
contract keys rather than hardcoded names.
- Expand session key primitives in `src/runtime/session-key.ts` with
`buildSlashSessionKey(...)` for mode-aware slash behavior (main/thread/
isolated + DM/thread fallback).
- Update slash execution flow in `src/index.ts` to carry compiled listener
session mode through session initialization, persistence metadata, and run
lifecycle policy logging.
Store/docs/invariants alignment
- Replace connector-oriented shared doc path with resource-oriented path:
- remove `store/shared/connectors/duckdb.md`
- add `store/shared/resources/duckdb.md`
- add `store/shared/resources/knowledge-docs.md`
- Add shared capability-backed skills:
- `store/shared/skills/duckdb-query.md`
- `store/shared/skills/knowledge-docs-review.md`
- Update repo invariants and CP5 verification harness for shared resources +
required shared skills:
- `scripts/test-invariants.mjs`
- `scripts/verify-cp5.ts`
Test coverage updates
- Add focused unit coverage for new seams:
- `tests/agents/capability-compiler.test.ts`
- `tests/resources/registry.test.ts`
- `tests/runtime/context-assembler.test.ts`
- Expand/adjust existing suites for new contracts and behavior:
- `tests/agents/contracts.test.ts`
- `tests/agents/index.test.ts`
- `tests/runtime/config.test.ts`
- `tests/runtime/executor-manager.test.ts`
- `tests/runtime/session-key.test.ts`
Documentation updates
- Update architecture/system-map/interface docs to describe the new
capability-first model, resource plugins, and runtime ownership/rollback
seams.
- Refresh checkpoint + active-plan docs to reflect CP6 priority and contract
language (`resources`/`useCapabilities` vs connectors/tools).
- Update runbook/mvp requirements/tech-debt wording from connector model to
resource model.
Validation
- Ran `npm run check` successfully (typecheck, unit tests, markdown lint,
repo lint, invariants).
kgalang
changed the title
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
No description provided.