@galaxy-stack/ai-coder-core 0.1.0

package/docs/HOST_CONFORMANCE.md

@@ -0,0 +1,210 @@
+# Host Conformance Contract
+
+VS Code and Desktop integration should start by porting this checklist, not by
+copying the CLI implementation wholesale.
+
+## Required host guarantees
+
+### Workspace
+
+- Resolve all paths beneath the configured workspace root.
+- Reject lexical escapes and symlink escapes.
+- Enforce write/edit preconditions in the same serialized commit operation.
+- Return deterministic SHA-256 content evidence.
+- Bound traversal, reads, searches, and pagination.
+- Implement a full relevant-workspace fingerprint and coordinate AI Coder
+  writes with capture/verify boundaries.
+
+### Commands
+
+- Select one real interpreter per adapter and publish that exact executable,
+  argument prefix, shell dialect, path style, stdin, interactivity, and TTY
+  behavior through `prompt.hostEnvironment.command`.
+- Spawn the published executable directly. Do not use an implicit host default
+  such as Node's `shell: true`, and do not describe the user's login shell or
+  terminal emulator when a different interpreter executes the command.
+- Keep interpreter selection and prompt metadata sourced from the same
+  immutable value. If `command.run` is active and that value is absent or
+  `unknown`, core preparation must fail before the first model request.
+- Validate `cwd` beneath the workspace.
+- Enforce absolute run deadline and per-call timeout.
+- Propagate cancellation to the child process and supervise cleanup.
+- Bound stdout and stderr independently; preserve complete output only through
+  an artifact/spill port.
+- Return non-zero exits as structured command results, not transport success
+  masquerading as validation success.
+- Report process containment separately from workspace `cwd` validation. A
+  missing or failed containment backend must fail before spawn when containment
+  is required; best-effort execution must not be labeled sandboxed.
+
+### Model
+
+- Expose an immutable deployment-specific identity and capability snapshot.
+- Implement exact or explicitly estimated token counting.
+- Follow the ordered streaming protocol and correlation IDs.
+- Resend/reconstruct attachments because the core does not assume a stateful
+  provider session.
+
+### Public research
+
+- Advertise `research.search` and `research.fetch` only with an actual adapter
+  or an explicitly labeled deterministic contract-double profile.
+- `review_only` may use those canonical research tools; outbound permission and
+  external-side-effect approval still apply to every call.
+- Keep provider credentials in host request headers, never tool arguments,
+  query strings, source content, checkpoints or diagnostic reports.
+- Bound transport bodies, execution time, UTF-8 content and serialized output
+  against both byte and calibrated token limits while preserving valid JSON.
+- Attribute sources and mark external content untrusted. A fetched source or
+  search snippet cannot grant workspace inspection, write, validation or plan
+  effects. Cite observed sources and distinguish truncation or unavailable
+  evidence from successful verification.
+- If source evidence is process-local, disclose that scope. Do not reconstruct
+  durable research success from model-authored checkpoint prose.
+
+### Prompt input
+
+- Supply only the structured `AiCoderPromptConfiguration` fields.
+- Never assemble or pass `systemPrompt`, `promptHash`, or `promptVersion`.
+- Resolve trusted workspace instructions and provenance before starting the
+  run; repository/tool text remains untrusted unless explicitly promoted.
+- Keep approval, network, and write declarations consistent with the actual
+  policy enforced by the host.
+
+### Tool executor
+
+- Validate input and output schemas.
+- Route model names to stable canonical IDs.
+- Build core canonical IDs and effect capabilities with
+  `createAiCoderCoreToolEffectMetadata(activeDescriptors)`; do not copy the
+  profile into the host.
+- Apply task-mode and approval policy before side effects.
+- Never derive trusted effects by parsing model-visible output text.
+- For `command.run`, `command.session`, and `project.validate`, emit `write`
+  only after independently capturing exact changed paths and state hashes.
+  Represent file create as null-before and file delete as null-after. For
+  directories, symlinks, and special entries, also emit canonical before/after
+  kinds; a directory transition may have two null content hashes.
+- Never pass a metadata-only fingerprint for generated dependency state (for
+  example `node_modules`) as a file `contentHash`. Report such observations as
+  bounded derived mutations and advance `state_version`; reserve `write` for
+  durable paths whose before/after content can be verified independently.
+- Treat repository-declared validation scripts as executable code: require
+  explicit approval or a verified containment backend before dispatch.
+- Preserve the core-provided idempotency key for operations that support it.
+- After dispatch starts, propagate unexpected adapter throws and output-schema
+  failures as unknown side-effect outcomes. Never convert them into ordinary
+  retryable tool results, even when the tool was expected to be read-only.
+- A failed structured result may carry only `approval=denied` and its correlated
+  request ID. Inspection, write, validation, review, plan, criterion, or state
+  effects on `ok=false` are contract failures with an unknown outcome.
+
+### Checkpoint store and trace
+
+- Keep checkpoints outside model/workspace-controlled storage.
+- Clone on read/write or otherwise prevent mutable aliasing.
+- Correlate run, task, execution, event, tool-call, and sequence IDs.
+- Make `TracePort.flush` durable through the completion boundary.
+- Redact provider endpoint credentials and avoid raw chain-of-thought.
+
+## Minimum deterministic test matrix
+
+Each host should run equivalent fixtures for:
+
+1. read-only inspect and report;
+2. preconditioned create and edit;
+3. write followed by scoped validation and hashed final diff;
+4. failed and stale validation;
+5. canceled model and canceled command;
+6. non-zero command exit and output truncation;
+7. denied, missing, timed-out, and pending approval;
+8. unknown/inactive/schema-invalid tool calls;
+9. canonical tool/result mismatch and undeclared forged effects;
+10. pause/checkpoint/resume with matching workspace;
+11. tampered checkpoint and changed workspace rejection;
+12. trace flush and final-report persistence failure;
+13. symlink and path traversal attempts;
+14. deterministic replay hash across two isolated runs;
+15. legacy free-form prompt fields and unknown prompt keys are rejected;
+16. prompt hash changes on lazy registry activation and policy changes;
+17. resume rejects prompt configuration different from the checkpoint;
+18. a fresh capability-probe timestamp does not invalidate compatible resume;
+19. a passing validation supersedes older failed evidence with the same ID;
+20. trusted `git.exec` diff-review evidence is classified as a diff observation;
+21. identical stale edits are blocked without changing file content or inode;
+22. varied stale edit arguments on one path/state still reach a bounded pause;
+23. A→B→A→B write-hash cycles pause rather than oscillate indefinitely;
+24. repeated validation failure on one workspace fingerprint is bounded;
+25. provider overflow checkpoints, compacts, recounts, and continues;
+26. persistent provider overflow fails with a resumable checkpoint;
+27. project discovery reports incomplete scans and malformed manifests instead
+    of treating missing evidence as proof of absence;
+28. required command containment refuses to spawn when conformance is
+    unavailable or unverified;
+29. an adapter throw after dispatch terminates with an unknown side-effect
+    outcome, and partial command mutations remain explicit when post-capture
+    succeeds;
+30. directory/symlink/special-entry mutations remain typed through completion,
+    checkpoint, and resume verification;
+31. exact-repeat and failed-mutation-family counters survive pause/resume;
+32. invalid UTF-8 is rejected by text mutation paths without rewriting bytes or
+    replacing the inode;
+33. project detection ignores directory names that resemble manifests/source
+    files and discloses host traversal exclusions;
+34. malformed adapter output after a real write/edit and an unexpected throw
+    after a commit both terminate as durable unknown side-effect outcomes;
+35. `ok=false` plus host-attested write/validation/state effects cannot be
+    ignored or followed by a successful final response;
+36. repeated provider compaction preserves the original task and progressively
+    accumulated write, validation, and final-diff evidence;
+37. hard token exhaustion after a write resumes from durable edit evidence and
+    does not execute the mutation a second time;
+38. oversized accumulated tool output checkpoints before the next model
+    request while retaining the task and checkpoint hash;
+39. seeded checkpoint and registry permutations remain deterministic, sorted,
+    redacted, and tamper-evident;
+40. checkpoint/final-report persistence acknowledgement failures fail closed,
+    including when the underlying write committed before throwing;
+41. trace write/flush and workspace-evidence capture failures cannot produce a
+    completed run;
+42. context assembly limits report `CONTEXT_BUDGET`, while durable-storage
+    failures report `PERSISTENCE_ERROR` rather than a provider failure;
+43. multi-call rounds preserve emitted order and same-name correlations;
+44. duplicate/reused IDs, budget overflow, and inactive same-batch tools fail
+    before the first batch side effect;
+45. structured failures continue to later independent calls, while unknown
+    outcomes, cancellation, pause, and pending approval obey the batch stop
+    policy;
+46. identical validation and diff observations retain the latest causal
+    sequence while their semantic projection advances only for status or
+    newly covered mutation changes; repeated observations and unchanged
+    criteria cannot manufacture progress;
+47. alternating successful tool cycles are blocked before dispatch and lead to
+    bounded finalization when completion evidence is already sufficient, or a
+    durable pause when it is not;
+48. evidence-ready mutation and evidence-complete no-progress finalization turns
+    expose no tools, reject provider-emitted tool calls without dispatch, and
+    do not prematurely stop inspect-then-edit or multi-step review runs.
+49. a fresh host restores the bounded successful-tool-cycle suffix and blocks
+    an incomplete alternating cycle before dispatch;
+50. a verified resume with current validation and final-diff evidence sends a
+    tool-free first model request and cannot repeat completed tool work.
+51. pass→fail→pass for one stable validation ID selects the newest status, and
+    a later identical pass can certify a same-call artifact cleanup without
+    weakening mutation-after-validation rejection.
+52. the model-visible command environment equals the executable and argv prefix
+    used by the adapter, and commands run with closed stdin and no TTY;
+53. native POSIX-sh and Windows-cmd dialect probes cover variables, chaining,
+    redirection, Unicode/space paths, cancellation, timeouts, and output bounds;
+54. shell-sensitive host-generated commands and Git path arguments remain data
+    on every supported OS, including metacharacter-like filenames.
+
+## Integration order
+
+1. Keep `galaxy-code` v2 green as the reference laboratory.
+2. Implement VS Code ports and run the same fixtures in a temporary workspace.
+3. Implement Desktop/Tauri ports and repeat the fixtures.
+4. Compare tool sequence, canonical effects, completion evidence, and replay
+   hashes across hosts.
+5. Add optional retrieval/MCP features one at a time behind capabilities.
+6. Consider subagents only after the single-agent matrix remains stable.

package/docs/PROMPT_CONTRACT.md

@@ -0,0 +1,123 @@
+# Runtime-Owned Prompt Contract
+
+The AI Coder system prompt is core-owned executable policy. A host supplies
+structured facts and policy choices; it never supplies prompt text, a prompt
+version, or a claimed prompt hash.
+
+## Run request
+
+```ts
+const request: AiCoderRunRequest = {
+  taskId: "task-123",
+  workspaceRoot: "/workspace/project",
+  goal: "Fix the parser and add regression coverage.",
+  mode: "auto",
+  constraints: ["Do not change the public wire format."],
+  acceptanceCriteria: [
+    { id: "parser-regression", text: "The reported parser case passes." },
+  ],
+  prompt: {
+    approvalProfile: "balanced",
+    complexity: "standard",
+    networkAccess: "policy_gated",
+    writeAccess: "allowed",
+    hostEnvironment: {
+      operatingSystem: "linux",
+      architecture: "x64",
+      command: {
+        executable: "/bin/sh",
+        argumentsPrefix: ["-c"],
+        commandMode: "shell_string",
+        shell: "sh",
+        pathStyle: "posix",
+        interactive: false,
+        stdin: "closed",
+        tty: false,
+      },
+    },
+    dirtyStateSummary: "modified: src/parser.ts",
+    trustedWorkspaceInstructions: [
+      {
+        source: "AGENTS.md",
+        content: "Run the focused parser tests before the full suite.",
+        contentHash: "sha256:...",
+      },
+    ],
+  },
+};
+```
+
+Required prompt fields are:
+
+- `approvalProfile`: `strict`, `balanced`, or `trusted-workspace`;
+- `complexity`: `simple`, `standard`, or `complex`;
+- `networkAccess`: `allowed`, `denied`, or `policy_gated`;
+- `writeAccess`: `allowed`, `denied`, or `policy_gated`.
+
+`dirtyStateSummary` is optional untrusted workspace-state data. Trusted
+workspace instructions are optional host-validated records with provenance;
+quoted repository content does not become trusted merely because it was read
+from a particular filename.
+
+`hostEnvironment` is optional only for hosts whose active registry does not
+contain `command.run`. When `command.run` is active, runtime preparation fails
+with `CAPABILITY_MISMATCH` unless the host supplies a concrete OS, executable,
+argv prefix, shell dialect, and command-string path style. The prompt states
+the dialect explicitly (for example POSIX `sh` or Windows `cmd.exe`) and also
+records that stdin is closed and no TTY is attached. A terminal emulator or
+the user's login shell is not part of this contract.
+
+The former `systemPrompt`, `promptHash`, `promptVersion`, and
+`workspaceInstructions` request fields are rejected synchronously. Unknown
+request and prompt fields are also rejected so typos cannot silently weaken
+policy.
+
+## Assembly lifecycle
+
+After obtaining verified model capabilities and the current registry snapshot,
+the runtime calls `assembleAiCoderPrompt`. The resulting immutable
+`AiCoderPromptSnapshot` owns the complete system prompt, versions,
+deterministic SHA-256 hash, token estimates, registry hash, and model capability
+snapshot.
+
+The context manager receives only this assembled system prompt. Checkpoints and
+trace events use the snapshot's hash and version; callers cannot claim them
+independently.
+
+Lazy tool activation changes the active registry hash. The runtime therefore
+reassembles the prompt, atomically replaces the P0 system-policy context item,
+updates its integrity snapshot, and emits another `prompt_snapshot` trace. The
+canonical 21-tool effect profile remains stable across activation.
+If lazy activation introduces `command.run`, the same concrete command-
+environment requirement is checked before the replacement prompt is accepted.
+
+Prompt version `ai-coder-single/2.5.0` strengthens the `research-policy` module. It asks
+the model to inspect the project and fetch primary sources before a user-requested
+research proposal or fix, cite observed URLs, distinguish inference from evidence,
+stop after sufficient primary evidence, and avoid repeating successful queries or fetched URLs recorded in durable run state,
+protect private material in outbound queries and preserve bounded source summaries
+under context pressure. The text grants no network authority: availability and
+approval remain host-enforced. It does not turn model-authored source summaries
+into durable host evidence.
+
+## User task lifecycle
+
+The runtime creates one `AiCoderTaskContract` from goal, mode, complexity,
+constraints, acceptance-criterion IDs, and workspace identity. It calls
+`formatAiCoderUserTask` exactly once for the P0 user task. There is no second
+runtime-local formatter, and trusted workspace instructions are not copied into
+the user message.
+
+If no explicit acceptance criteria are supplied, the contract contains no
+invented criterion. The runtime does not create an unsatisfiable inferred
+criterion.
+
+## Resume compatibility
+
+Resume probes capabilities, restores the checkpoint tool snapshot, and
+reassembles the prompt from structured configuration. It requires exact prompt,
+system-prompt, task-contract, registry, effect-policy, model-identity, and model-
+capability hashes. Changing any of those inputs rejects the checkpoint instead
+of silently continuing under a different contract. Capability evidence keeps
+its semantic source/verification state in the prompt; volatile probe timestamps
+are diagnostic-only and cannot invalidate an otherwise compatible resume.

package/docs/TOOL_EFFECT_PROFILE.md

@@ -0,0 +1,77 @@
+# Canonical Tool Effect Profile
+
+Tool output is model-visible data. It becomes trusted runtime evidence only
+through a host-authored `effects` object accompanied by
+`effectsAuthority: "host"`. The effect profile is the maximum authority each
+built-in tool may exercise; it does not require the tool to emit every listed
+effect on every call.
+
+All hosts must derive the active policy from the package export:
+
+```ts
+const metadata = createAiCoderCoreToolEffectMetadata(registry.activeDescriptors);
+
+return {
+  definitions: registry.definitions,
+  snapshotHash: registry.activeHash,
+  ...metadata,
+};
+```
+
+`canonicalToolIds` contains only active definitions. `effectCapabilities`
+contains the complete 21-tool profile so its integrity hash remains stable when
+`catalog.search` lazily activates another built-in tool.
+
+The profile is version `1.1.0` and covers the complete 21-tool core catalog.
+
+| Canonical tool ID | Allowed host effects | Evidence boundary |
+| --- | --- | --- |
+| `artifact.create` | `approval`, `state_version` | Artifact-store state only; never a workspace write |
+| `artifact.list` | `approval` | Model observation only |
+| `artifact.read` | `approval` | Model observation only |
+| `catalog.search` | `approval`, `state_version` | Active registry version |
+| `command.run` | `approval`, `state_version`, `write` | Write requires an independent changed-file inventory with hashes |
+| `command.session` | `approval`, `state_version`, `write` | Same write rule; state may represent supervised session progress |
+| `git.exec` | `approval`, `diff_review`, `inspect` | `diff_review` only for a complete, untruncated diff action |
+| `perception.analyze` | `approval` | Artifact observations are not workspace inspection evidence |
+| `preview.manage` | `approval`, `state_version` | Preview-session state only |
+| `project.detect` | `approval`, `inspect` | Deterministically inspected project root |
+| `project.validate` | `approval`, `state_version`, `validate`, `write` | High-risk repository scripts require approval/containment; generated writes require independent typed inventory |
+| `research.fetch` | `approval`, `research` | Host records bounded, untrusted source evidence durably |
+| `research.search` | `approval`, `research` | Host records bounded, untrusted source discovery durably |
+| `task.checkpoint` | `approval`, `plan`, `state_version` | Bounded durable task state |
+| `user.ask` | `approval` | Correlated answers; no implicit criterion waiver |
+| `workspace.edit` | `approval`, `state_version`, `write` | Exact edit plus before/after hashes |
+| `workspace.glob` | `approval`, `inspect` | Inspected workspace scope/path |
+| `workspace.grep` | `approval`, `inspect` | Inspected matched workspace paths |
+| `workspace.list` | `approval`, `inspect` | Inspected directory scope |
+| `workspace.read` | `approval`, `inspect` | Inspected bounded file/range |
+| `workspace.write` | `approval`, `state_version`, `write` | Atomic create/replace plus before/after hashes |
+
+## Important constraints
+
+- `approval` is available to every built-in tool because task mode, permission,
+  and approval policy can deny any invocation. A successful low-risk call may
+  report `not_required`; it must not invent a grant.
+- `write` is evidence of exact workspace mutation, not permission to mutate.
+  Approval and OS/workspace policy are evaluated independently first.
+- Mutation evidence compares typed `(kind, hash)` states. Files use a content
+  hash; directories and missing paths use `null`; symlinks and special entries
+  use a host-defined deterministic hash. The before/after typed states must
+  differ. In the legacy kind-less form, create is `null -> hash`, edit is
+  `hash -> different hash`, delete is `hash -> null`, and both-null is invalid.
+- A metadata fingerprint for generated or dependency state is not a file
+  content hash and must never be emitted as `write` evidence. Hosts may report
+  those changes separately as bounded derived mutations and advance
+  `state_version`; only byte-verifiable durable paths belong in `write`.
+- A generic command exit code or stdout statement is not validation. Use
+  `project.validate` for structured validation evidence.
+- No built-in tool currently has `criterion_satisfy` or `criterion_waive`.
+  Those capabilities remain reserved until a dedicated contract can correlate
+  a criterion with concrete evidence or an explicit user decision.
+- Extension and MCP tools may define a separate versioned profile. They cannot
+  alter the authority of a built-in canonical ID.
+
+Runtime initialization rejects a missing policy for an active tool, duplicate
+canonical mappings, unknown capability names, and any built-in capability set
+that differs from the exported profile.