@cat-factory/kernel 0.7.3 → 0.8.0

package/dist/ports/agent-definition.d.ts

@@ -0,0 +1,62 @@
+import type { AgentRunContext, AgentRunResult } from './agent-executor.js';
+import type { RepoFiles } from './repo-files.js';
+/** Where an agent's LLM step runs. */
+export type AgentSurface = 
+/** A one-shot inline LLM call over the provided context — no repo, no container. */
+'inline'
+/** A read-only container run: clone + explore + return prose or structured JSON; no push. */
+ | 'container-explore'
+/** A container run that edits a working tree and commits + pushes (optionally opens a PR). */
+ | 'container-coding';
+/** How an explore agent's reply is consumed. */
+export interface AgentOutputSpec {
+    /** `prose` keeps the reply as text; `structured` parses + (optionally) repairs it to JSON. */
+    kind: 'prose' | 'structured';
+    /**
+     * Compact human description of the expected JSON shape, fed to the harness's one-shot
+     * structured-output repair call when the first parse fails. Structured kind only.
+     */
+    shapeHint?: string;
+    /** Whether to attempt the one-shot structured-output repair on a malformed reply. */
+    repair?: boolean;
+}
+/** What a container agent clones (resolved to a concrete branch by the engine at dispatch). */
+export interface AgentCloneSpec {
+    /** Which branch to check out: the base branch, the block's PR branch, or the work branch. */
+    branch: 'base' | 'pr' | 'work';
+    /** A monorepo subtree to sparse-checkout (storage optimisation); absent ⇒ whole repo. */
+    sparsePaths?: string[];
+    /** Full history (needed to diff against base / merge); absent ⇒ shallow. */
+    full?: boolean;
+}
+/** The optional LLM step of an agent definition. */
+export interface AgentStepSpec {
+    surface: AgentSurface;
+    output?: AgentOutputSpec;
+    /** Container surfaces only: what to clone. */
+    clone?: AgentCloneSpec;
+    /** Container coding surface only: how to stand dependencies up (tester). */
+    infra?: 'none' | 'compose' | 'ephemeral-url';
+}
+/** Context handed to a {@link RepoOp}. */
+export interface RepoOpContext {
+    /** Per-run, checkout-free repo access bound to the run's installation + repo. */
+    repo: RepoFiles;
+    /** The run/block/task context (branch, block id, task description, prior outputs). */
+    context: AgentRunContext;
+    /** The branch the op reads/writes (the engine resolves base/pr/work to a concrete name). */
+    branch: string;
+    /**
+     * The finished agent's structured result. Present for postOps (which consume it —
+     * e.g. render `spec/` from `result.spec`); absent for preOps.
+     */
+    result?: AgentRunResult;
+}
+/**
+ * Deterministic backend logic run before/after an agent step, over a checkout-free
+ * {@link RepoFiles}. A preOp prepares inputs (read a baseline artifact); a postOp
+ * consumes the agent's structured output (render + commit artifact files). Pure of
+ * container concerns; throwing fails the step.
+ */
+export type RepoOp = (ctx: RepoOpContext) => Promise<void>;
+//# sourceMappingURL=agent-definition.d.ts.map

package/dist/ports/agent-definition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-definition.d.ts","sourceRoot":"","sources":["../../src/ports/agent-definition.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AAC1E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAoBhD,sCAAsC;AACtC,MAAM,MAAM,YAAY;AACtB,oFAAoF;AAClF,QAAQ;AACV,6FAA6F;GAC3F,mBAAmB;AACrB,8FAA8F;GAC5F,kBAAkB,CAAA;AAEtB,gDAAgD;AAChD,MAAM,WAAW,eAAe;IAC9B,8FAA8F;IAC9F,IAAI,EAAE,OAAO,GAAG,YAAY,CAAA;IAC5B;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,qFAAqF;IACrF,MAAM,CAAC,EAAE,OAAO,CAAA;CACjB;AAED,+FAA+F;AAC/F,MAAM,WAAW,cAAc;IAC7B,6FAA6F;IAC7F,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAAA;IAC9B,yFAAyF;IACzF,WAAW,CAAC,EAAE,MAAM,EAAE,CAAA;IACtB,4EAA4E;IAC5E,IAAI,CAAC,EAAE,OAAO,CAAA;CACf;AAED,oDAAoD;AACpD,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,YAAY,CAAA;IACrB,MAAM,CAAC,EAAE,eAAe,CAAA;IACxB,8CAA8C;IAC9C,KAAK,CAAC,EAAE,cAAc,CAAA;IACtB,4EAA4E;IAC5E,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,eAAe,CAAA;CAC7C;AAED,0CAA0C;AAC1C,MAAM,WAAW,aAAa;IAC5B,iFAAiF;IACjF,IAAI,EAAE,SAAS,CAAA;IACf,sFAAsF;IACtF,OAAO,EAAE,eAAe,CAAA;IACxB,4FAA4F;IAC5F,MAAM,EAAE,MAAM,CAAA;IACd;;;OAGG;IACH,MAAM,CAAC,EAAE,cAAc,CAAA;CACxB;AAED;;;;;GAKG;AACH,MAAM,MAAM,MAAM,GAAG,CAAC,GAAG,EAAE,aAAa,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA"}

package/dist/ports/agent-definition.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=agent-definition.js.map

package/dist/ports/agent-definition.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-definition.js","sourceRoot":"","sources":["../../src/ports/agent-definition.ts"],"names":[],"mappings":""}

package/dist/ports/index.d.ts

@@ -23,6 +23,8 @@ export { type WorkRunner, NoopWorkRunner } from './work-runner.js';
 export { type ExecutionEventPublisher, NoopEventPublisher } from './execution-events.js';
 export type { CommitFilesResult, GitHubClient, GitHubCodeSearchHit, GitHubIssueComment, GitHubIssueDetail, GitHubIssueSearchHit, GitHubRepoRef, InstallationMeta, InstallationSummary, ListOptions, Paged, RateLimitSnapshot, RepoContentEntry, RepoEntry, RepoFileContent, } from './github-client.js';
 export type { CreateRepoInput, GitHubProvisioningClient, InstallationPermissions, ProvisionedRepo, } from './github-provisioning.js';
+export type { RepoFiles, ResolveRepoFiles } from './repo-files.js';
+export type { AgentCloneSpec, AgentOutputSpec, AgentStepSpec, AgentSurface, RepoOp, RepoOpContext, } from './agent-definition.js';
 export type { BranchProjectionRepository, CheckRunProjectionRepository, CommitProjectionRepository, GitHubInstallation, GitHubInstallationRepository, IssueProjectionRepository, PullRequestProjectionRepository, RateLimitRepository, RepoProjectionRepository, StaleRepoRef, SyncCursor, SyncCursorKind, } from './github-repositories.js';
 export type { WebhookVerifier } from './webhook-verifier.js';
 export type { DocumentCredentials, DocumentContent, NormalizedConnection, DocumentSourceProvider, DocumentSourceRegistry, } from './document-source.js';

package/dist/ports/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ports/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ports/index.ts"],"names":[],"mappings":"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"}

package/dist/ports/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/ports/index.ts"],"names":[],"mappings":"AAqDA,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AAQpD,OAAO,EAAE,0BAA0B,EAAE,MAAM,kBAAkB,CAAA;AAQ7D,OAAO,EACL,uBAAuB,EACvB,uBAAuB,EACvB,8BAA8B,GAC/B,MAAM,qBAAqB,CAAA;AAW5B,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAA;AAC1D,OAAO,EAAmB,cAAc,EAAE,MAAM,kBAAkB,CAAA;AAClE,OAAO,EAAgC,kBAAkB,EAAE,MAAM,uBAAuB,CAAA;AA6FxF,OAAO,EAAwB,wBAAwB,EAAE,MAAM,wBAAwB,CAAA;AAuBvF,OAAO,EAAwB,mBAAmB,EAAE,MAAM,uBAAuB,CAAA;AA2DjF,OAAO,EAAE,mCAAmC,EAAE,MAAM,0BAA0B,CAAA;AAmC9E,OAAO,EAEL,4BAA4B,EAC5B,uBAAuB,GACxB,MAAM,2BAA2B,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/ports/index.ts"],"names":[],"mappings":"AAqDA,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AAQpD,OAAO,EAAE,0BAA0B,EAAE,MAAM,kBAAkB,CAAA;AAQ7D,OAAO,EACL,uBAAuB,EACvB,uBAAuB,EACvB,8BAA8B,GAC/B,MAAM,qBAAqB,CAAA;AAW5B,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAA;AAC1D,OAAO,EAAmB,cAAc,EAAE,MAAM,kBAAkB,CAAA;AAClE,OAAO,EAAgC,kBAAkB,EAAE,MAAM,uBAAuB,CAAA;AAsGxF,OAAO,EAAwB,wBAAwB,EAAE,MAAM,wBAAwB,CAAA;AAuBvF,OAAO,EAAwB,mBAAmB,EAAE,MAAM,uBAAuB,CAAA;AA2DjF,OAAO,EAAE,mCAAmC,EAAE,MAAM,0BAA0B,CAAA;AAmC9E,OAAO,EAEL,4BAA4B,EAC5B,uBAAuB,GACxB,MAAM,2BAA2B,CAAA"}

package/dist/ports/repo-files.d.ts

@@ -0,0 +1,40 @@
+import type { CommitFilesInput, GitHubPullRequest, OpenPullRequestInput } from '../domain/types.js';
+import type { CommitFilesResult, GitHubRepoRef, RepoContentEntry, RepoFileContent } from './github-client.js';
+export interface RepoFiles {
+    /**
+     * Read a file's decoded UTF-8 content + blob sha on `gitRef` (a branch, tag or sha;
+     * defaults to the repo's default branch), or null when the path is absent. Used by a
+     * pre-op to read a baseline artifact (e.g. `spec/spec.json`) into the agent's prompt,
+     * and by a post-op to read the prior `version.json` for the staleness counter.
+     */
+    getFile(path: string, gitRef?: string): Promise<RepoFileContent | null>;
+    /**
+     * List a directory's entries on `gitRef`, or `[]` when the path is absent. Used by the
+     * spec post-op to seed Gherkin feature files only when they don't already exist.
+     */
+    listDirectory(path: string, gitRef?: string): Promise<RepoContentEntry[]>;
+    /**
+     * The head commit sha of `branch`, or null when the branch does not exist. Lets a
+     * post-op decide create-vs-commit (the spec-writer runs before the coder, so its
+     * branch may not exist yet) and resolve a base sha for {@link createBranch}.
+     */
+    headSha(branch: string): Promise<string | null>;
+    /** Create `branch` pointing at `fromSha` (e.g. the default branch's head). */
+    createBranch(branch: string, fromSha: string): Promise<void>;
+    /**
+     * Commit a set of files onto a branch via the Git Data API (blob → tree → commit →
+     * ref). Mirrors {@link GitHubClient.commitFiles}; the bound installation/repo are
+     * implicit. An empty/no-op change is the caller's concern (render is deterministic,
+     * so re-committing identical bytes is avoided by comparing the version hash).
+     */
+    commitFiles(input: CommitFilesInput): Promise<CommitFilesResult>;
+    /** Open a pull request (idempotent: returns the existing open PR if one matches head/base). */
+    openPullRequest(input: OpenPullRequestInput): Promise<GitHubPullRequest>;
+}
+/**
+ * Build a {@link RepoFiles} bound to a workspace's GitHub installation + a repo. The
+ * server implements this over the wired {@link GitHubClient}; the engine resolves the
+ * installation id + repo ref for a run and hands the bound facade to pre/post-ops.
+ */
+export type ResolveRepoFiles = (installationId: number, ref: GitHubRepoRef) => RepoFiles;
+//# sourceMappingURL=repo-files.d.ts.map

package/dist/ports/repo-files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"repo-files.d.ts","sourceRoot":"","sources":["../../src/ports/repo-files.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAA;AACnG,OAAO,KAAK,EACV,iBAAiB,EACjB,aAAa,EACb,gBAAgB,EAChB,eAAe,EAChB,MAAM,oBAAoB,CAAA;AAiB3B,MAAM,WAAW,SAAS;IACxB;;;;;OAKG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAAA;IACvE;;;OAGG;IACH,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAAA;IACzE;;;;OAIG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAA;IAC/C,8EAA8E;IAC9E,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC5D;;;;;OAKG;IACH,WAAW,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAA;IAChE,+FAA+F;IAC/F,eAAe,CAAC,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAA;CACzE;AAED;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,cAAc,EAAE,MAAM,EAAE,GAAG,EAAE,aAAa,KAAK,SAAS,CAAA"}

package/dist/ports/repo-files.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=repo-files.js.map

package/dist/ports/repo-files.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"repo-files.js","sourceRoot":"","sources":["../../src/ports/repo-files.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/kernel",
-  "version": "0.7.3",
+  "version": "0.8.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/kibertoad/cat-factory.git",
@@ -25,7 +25,7 @@
   },
   "dependencies": {
     "ai": "^6.0.208",
-    "@cat-factory/contracts": "0.7.2"
+    "@cat-factory/contracts": "0.8.0"
   },
   "devDependencies": {
     "typescript": "7.0.1-rc"