From 3a2b2264c116ea61829ae0b97987e8b4eaa2fb00 Mon Sep 17 00:00:00 2001 From: Taras Mankovski Date: Sun, 15 Nov 2026 12:13:54 -0500 Subject: [PATCH 1/6] Spike scoped approval for journal appends --- packages/core/host.ts | 3 +- packages/core/src/agent/conversation.ts | 66 ++--- packages/core/src/execute.ts | 77 ++++-- packages/core/src/secrets/append-approval.ts | 103 ++++++++ packages/core/src/secrets/policy.ts | 50 +--- packages/core/src/secrets/reply-grant.ts | 248 +----------------- packages/core/src/secrets/secret-placement.ts | 171 ++++++++++++ packages/core/tests/append-approval.test.ts | 151 +++++++++++ 8 files changed, 534 insertions(+), 335 deletions(-) create mode 100644 packages/core/src/secrets/append-approval.ts create mode 100644 packages/core/src/secrets/secret-placement.ts create mode 100644 packages/core/tests/append-approval.test.ts diff --git a/packages/core/host.ts b/packages/core/host.ts index a9b683a74..f5b86f07d 100644 --- a/packages/core/host.ts +++ b/packages/core/host.ts @@ -67,7 +67,8 @@ * reader: nothing published, nothing named, and nothing for a same-name context * or a second loaded copy to reach. */ -export { executeInstalled } from "./src/execute.ts"; +export { executeInstalled, executeInstalledWithApprovals } from "./src/execute.ts"; +export type { AppendApproval, AppendApprovals } from "./src/secrets/append-approval.ts"; /** * `ExecutionInitialization` is the fourth, and it is input rather than * infrastructure: the root JSON bindings one execution starts with, supplied diff --git a/packages/core/src/agent/conversation.ts b/packages/core/src/agent/conversation.ts index e34a74cad..77af235c3 100644 --- a/packages/core/src/agent/conversation.ts +++ b/packages/core/src/agent/conversation.ts @@ -83,7 +83,8 @@ import type { } from "@executablemd/durable-streams"; import { executeInstalledBound } from "../execute.ts"; -import type { ExecutionInstallation } from "../execute.ts"; +import type { BoundExecution, ExecutionInstallation } from "../execute.ts"; +import type { AppendApprovals } from "../secrets/append-approval.ts"; import type { BoundRootEvaluator } from "../generated-root-owner.ts"; import type { AcceptedRootReply, @@ -95,14 +96,12 @@ import { isJsonObject, parseJson } from "../json.ts"; import { retainedSource } from "../root-source.ts"; import { captureReplyTextCheck, - grantReplyCopies, locateReplySecrets, scanSecrets, secretPolicy, } from "../secrets/policy.ts"; import type { ReplyTextCheck } from "../secrets/policy.ts"; import { - acceptanceGrant, approvedMatches, carriedCopies, evaluationGrant, @@ -673,6 +672,8 @@ function handle( }; } +type ConversationBinding = Omit; + /** * Run the conversation's own durable root, and serve turns inside it forever. * @@ -719,11 +720,9 @@ function* serve( // `executeInstalled` is about to return, so the bound evaluator does not // exist yet when the body begins. The bridge is how the two meet: the // element waits for it before announcing the conversation ready, and this - // function resolves it as soon as the handle exists. It carries the bound - // operation and nothing else — no protected table, no route, no reference — - // and it is a local value rather than a context, so nothing running in the - // conversation can set, read or replace what the element waits on. - const bridge = withResolvers(); + // function resolves it as soon as the handle exists. The evaluator and + // journal permissions travel directly through this local value. + const bridge = withResolvers(); const installation: ExecutionInstallation = { components: [ { @@ -740,15 +739,14 @@ function* serve( ], }; try { - const execution = yield* executeInstalledBound( + const { execution, ...binding } = yield* executeInstalledBound( { ...retainedSource(CONVERSATION_ROOT_PATH, CONVERSATION_ROOT_SOURCE), stream: request.history, }, [...request.installations, installation], - undefined, - (evaluate) => bridge.resolve(evaluate), ); + bridge.resolve(binding); // Before the completion is waited on, and after the handle exists: the // element is suspended on this, and nothing it does decides whether this // resolves. @@ -789,7 +787,7 @@ function* held( history: ConversationHistory, jobs: Queue, announce: (outcome: Result) => void, - bridge: Resolvers, + bridge: Resolvers, live: Live, claim: IdentityClaimant, invocation: ComponentInvocation, @@ -845,7 +843,8 @@ function* held( // The actual method on this execution's own handle, waited for before the // conversation is announced: a handle that reported itself ready and then // refused to evaluate would be ready for two of the three things it offers. - const evaluate = yield* bridge.operation; + const binding = yield* bridge.operation; + const { evaluate } = binding; const checkReplyText = yield* captureReplyTextCheck(); live.checkReplyText = checkReplyText; announce(Ok(undefined)); @@ -896,6 +895,7 @@ function* held( live, carrying, checkReplyText, + binding, ); if (live.fatal !== undefined) { yield* suspend(); @@ -1137,6 +1137,7 @@ function deliver( live: Live, carrying: Carrying | undefined, checkReplyText: ReplyTextCheck, + bound: Pick, ): Operation { // Scoped, so the turn cannot outlive the call that asked for it however this // returns: a turn still running would hold its durable operation open, and @@ -1145,26 +1146,25 @@ function deliver( const copies = carrying === undefined ? [] : carriedCopies(job.input, carrying.slices, carrying.carried); const prepare = (delegated: string) => (delegated.startsWith(job.input) ? copies : []); + // Registered *before* the turn is spawned, which is what makes it the last + // thing to unwind: cleanups registered later run first, so the turn — and + // every cleanup the provider registered inside it — has finished by the + // time this reports the turn joined. A caller waiting on this therefore + // waits for the work, not for the request to stop being interesting. + yield* ensure(() => { + job.joined.resolve(); + }); // The one turn an accepted answer may be carried by, for exactly as long as // this turn runs: retired when it commits, fails or is cancelled. if (carrying !== undefined) { - const retire = yield* grantReplyCopies( + yield* bound.registerGrant( feedbackGrant({ type: AGENT_PROMPT, name: turnName(order), prepare, }), ); - yield* ensure(retire); } - // Registered *before* the turn is spawned, which is what makes it the last - // thing to unwind: cleanups registered later run first, so the turn — and - // every cleanup the provider registered inside it — has finished by the - // time this reports the turn joined. A caller waiting on this therefore - // waits for the work, not for the request to stop being interesting. - yield* ensure(() => { - job.joined.resolve(); - }); const turn = yield* spawn(() => conversationTurn( provider, @@ -1178,6 +1178,7 @@ function deliver( used, facts, live, + bound.approvals, job.automaticFeedback || carrying !== undefined ? (delegated) => checkReplyText(delegated, prepare(delegated)) : undefined, @@ -1244,6 +1245,7 @@ function conversationTurn( used: boolean, facts: SessionFacts, live: Live, + approvals: AppendApprovals, checkInput: ((text: string) => Operation) | undefined, ): Operation { return (function* (): Operation { @@ -1381,7 +1383,7 @@ function conversationTurn( const accepted = pending === undefined ? undefined - : yield* reviewWithheld(pending, carried.begun, turnName(order), live); + : yield* reviewWithheld(pending, carried.begun, turnName(order), live, approvals); job.answer.resolve( accepted === undefined ? Err(new AgentReplyWithheldError()) : Ok(accepted), ); @@ -1433,6 +1435,7 @@ function* reviewWithheld( begun: unknown, name: string, live: Live, + approvals: AppendApprovals, ): Operation { const hold: { current?: AgentReplyHold } = {}; const reviewed = yield* askReplyReview({ @@ -1476,14 +1479,15 @@ function* reviewWithheld( return undefined; } const approved = approvedMatches(pending.text, pending.spans); - const retire = yield* grantReplyCopies( - acceptanceGrant({ type: AGENT_PROMPT_REPLY, name, text: pending.text, approved }), - ); - try { + yield* scoped(function* () { + yield* approvals.approveAppend({ + coroutineId: "root", + type: AGENT_PROMPT_REPLY, + name, + fields: [{ path: ["result", "value", "text"], text: pending.text, matches: approved }], + }); yield* persistPromptReply(name, pending.text, approved); - } finally { - retire(); - } + }); live.accepted = { kind: "evaluation", text: pending.text, approved, hold: reviewed.hold }; return pending.text; } diff --git a/packages/core/src/execute.ts b/packages/core/src/execute.ts index e24bfd37a..aaf79736c 100644 --- a/packages/core/src/execute.ts +++ b/packages/core/src/execute.ts @@ -230,6 +230,12 @@ import { provideTestHarnessInstallers } from "./test-harness.ts"; import type { TestHarnessInstaller } from "./test-harness.ts"; import type { CheckedFailures } from "./component-failures.ts"; import { clearsLiveOutput, useSecretDetection } from "./secrets/policy.ts"; +import { useAppendApprovalOwner } from "./secrets/append-approval.ts"; +import type { + AppendApprovalOwner, + AppendApprovals, + AppendGrant, +} from "./secrets/append-approval.ts"; import { propsEnvironment } from "./eval-env.ts"; import { liveEnvironment, validateBindingName } from "./live-env.ts"; @@ -2970,6 +2976,7 @@ function* executeDocument( // established before there is a live reference for it to release. const inputs = yield* inputValues(); const computed = yield* useComputedBindings(inputs); + const approvalOwner = yield* useAppendApprovalOwner(); const registry = createModifierRegistry(); // Held by identity as well as by name: a bound block is authorized against @@ -3256,7 +3263,12 @@ function* executeDocument( // root component import is already behind the gate. What comes back is // the stream to journal through; the policy itself stays inside the // execution that owns it. - const detection = yield* useSecretDetection(secretDetection, stream, inputs); + const detection = yield* useSecretDetection( + secretDetection, + stream, + inputs, + approvalOwner.grants, + ); const journal = detection.journal; // Adopted here, where the policy is established, and held by value: a // reader asking this execution later must be answered by the scanner the @@ -3632,6 +3644,7 @@ function* executeDocument( output: channel, }, evaluateGeneratedXmdRoot: roots.evaluate, + approvalOwner, evaluation: roots.completion, computed, stop: stopDocument, @@ -3642,15 +3655,13 @@ function* executeDocument( * What canonical execution produces, before a public entrypoint decides how * much of it to publish. * - * Three members rather than one object with methods on it. The document handle - * is what every caller gets, and the bound evaluator travels beside it so that - * the ordinary `execute()` surface can hand over the handle alone — its runtime - * object then has no evaluator to find, by its own name or through its - * prototype, rather than one hidden behind a narrower annotation. + * The document handle is what every caller gets. The bound evaluator and + * append approvals travel beside it for hosts that ask for them. */ interface CanonicalInvocation { readonly execution: DocumentExecution; readonly evaluateGeneratedXmdRoot: BoundRootEvaluator; + readonly approvalOwner: AppendApprovalOwner; /** This execution's own computed root data, for the trusted handle to read. */ readonly computed: ComputedBindings; /** @@ -4048,6 +4059,7 @@ function* runInvocation( return { evaluateGeneratedXmdRoot: invoked.evaluateGeneratedXmdRoot, + approvalOwner: invoked.approvalOwner, computed: invoked.computed, stop: stopInvocation, // Carried through unchanged. The completion this handle publishes has @@ -4786,21 +4798,40 @@ function initialRootBindings( * host holds and passes, so a separately loaded workflow package composes by * handing its closure over rather than by agreeing on a name. */ -export function executeInstalled( +export function* executeInstalled( options: ExecuteOptions, installations: readonly ExecutionInstallation[], initialization?: ExecutionInitialization, ): Operation { - return executeInstalledBound(options, installations, initialization); + const { execution } = yield* executeInstalledBound(options, installations, initialization); + return execution; +} + +export function* executeInstalledWithApprovals( + options: ExecuteOptions, + installations: readonly ExecutionInstallation[], + initialization?: ExecutionInitialization, +): Operation<{ execution: HostExecution; approvals: AppendApprovals }> { + const { execution, approvals } = yield* executeInstalledBound( + options, + installations, + initialization, + ); + return { execution, approvals }; +} + +export interface BoundExecution { + readonly execution: HostExecution; + readonly evaluate: BoundRootEvaluator; + readonly approvals: AppendApprovals; + registerGrant(grant: AppendGrant): Operation; } -/** Hand the canonical evaluator directly to the held conversation. */ export function* executeInstalledBound( options: ExecuteOptions, installations: readonly ExecutionInstallation[], initialization?: ExecutionInitialization, - bindEvaluator?: (evaluate: BoundRootEvaluator) => void, -): Operation { +): Operation { const invoked = yield* runInvocation( options, [...installations], @@ -4814,23 +4845,27 @@ export function* executeInstalledBound( }, }); const { execution } = invoked; - bindEvaluator?.(invoked.evaluateGeneratedXmdRoot); const clearDisclosure = invoked.computed.disclose; // Assembled here, at the trusted boundary, and nowhere else. The document // handle this delegates to is the authoritative one: the consumer's own // `ensure` is registered in the consumer's scope exactly as before, so // halting a consumer still takes the invocation down with it. return { - output: execution.output, - *[Symbol.iterator]() { - return yield* execution; - }, - evaluateGeneratedXmdRoot: (request) => invoked.evaluateGeneratedXmdRoot(request), - bindings: invoked.computed.read, - disclose(data) { - return clearDisclosure(data, disclosure.operations.disclose); + execution: { + output: execution.output, + *[Symbol.iterator]() { + return yield* execution; + }, + evaluateGeneratedXmdRoot: (request) => invoked.evaluateGeneratedXmdRoot(request), + bindings: invoked.computed.read, + disclose(data) { + return clearDisclosure(data, disclosure.operations.disclose); + }, + stop: invoked.stop, }, - stop: invoked.stop, + evaluate: invoked.evaluateGeneratedXmdRoot, + approvals: invoked.approvalOwner.approvals, + registerGrant: invoked.approvalOwner.registerGrant, }; } diff --git a/packages/core/src/secrets/append-approval.ts b/packages/core/src/secrets/append-approval.ts new file mode 100644 index 000000000..543edc969 --- /dev/null +++ b/packages/core/src/secrets/append-approval.ts @@ -0,0 +1,103 @@ +import type { DurableEvent } from "@executablemd/durable-streams"; +import { ensure } from "effection"; +import type { Operation } from "effection"; +import { exactly, place, within } from "./secret-placement.ts"; +import type { Path } from "./secret-placement.ts"; +import type { SecretSpan } from "./scanner.ts"; + +export interface AppendApproval { + readonly coroutineId: string; + readonly type: string; + readonly name: string; + readonly fields: readonly { + readonly path: Path; + readonly text: string; + readonly matches: readonly SecretSpan[]; + }[]; +} + +export interface AppendApprovals { + /** Allow one matching append within the caller's scope. */ + approveAppend(approval: AppendApproval): Operation; +} + +export interface AppendGrant { + claims(event: DurableEvent): boolean; + admits(event: DurableEvent, serialized: string, spans: readonly SecretSpan[]): boolean; + published?(event: DurableEvent): void; +} + +export interface AppendApprovalOwner { + approvals: AppendApprovals; + grants: Set; + registerGrant(grant: AppendGrant): Operation; +} + +export function* useAppendApprovalOwner(): Operation { + const grants = new Set(); + let open = true; + yield* ensure(() => { + open = false; + grants.clear(); + }); + + function* registerGrant(grant: AppendGrant): Operation { + yield* ensure(() => { + grants.delete(grant); + }); + if (!open) { + throw new Error("this execution's append approvals are closed"); + } + grants.add(grant); + } + + return { + approvals: Object.freeze({ + approveAppend(approval: AppendApproval) { + return registerGrant(approvedAppend(approval)); + }, + }), + grants, + registerGrant, + }; +} + +function approvedAppend(approval: AppendApproval): AppendGrant { + const { coroutineId, type, name } = approval; + const fields = approval.fields.map(({ path, text, matches }) => ({ + path: [...path], + text, + matches: matches.map((match) => ({ ...match })), + })); + let used = false; + function claims(event: DurableEvent): boolean { + return ( + !used && + event.type === "yield" && + event.coroutineId === coroutineId && + event.description.type === type && + event.description.name === name + ); + } + return { + claims, + admits(event, serialized, spans) { + if (!claims(event)) { + return false; + } + used = true; + const placed = place( + serialized, + fields.map(({ path }) => path), + ); + return ( + placed !== undefined && + placed.every((field, index) => field.value === fields[index].text) && + spans.every((span) => { + const at = within(placed, span); + return at !== undefined && exactly(fields[at.leaf].matches, span, at.start, at.end); + }) + ); + }, + }; +} diff --git a/packages/core/src/secrets/policy.ts b/packages/core/src/secrets/policy.ts index 637cccd28..bd7dafb1d 100644 --- a/packages/core/src/secrets/policy.ts +++ b/packages/core/src/secrets/policy.ts @@ -48,8 +48,9 @@ import { SecretDetectedError, SecretScannerError } from "./findings.ts"; import type { SecretFinding } from "./findings.ts"; import { createSecretScanner, locateSecrets } from "./scanner.ts"; import type { SecretScanner, SecretSpan } from "./scanner.ts"; -import { boundariesOf } from "./reply-grant.ts"; -import type { ApprovedMatch, ReplyCopyGrant } from "./reply-grant.ts"; +import { boundariesOf } from "./secret-placement.ts"; +import type { ApprovedMatch } from "./secret-placement.ts"; +import type { AppendGrant } from "./append-approval.ts"; import type { JsonObject } from "../types.ts"; /** @@ -94,24 +95,11 @@ class EnabledDetection extends ExecutionDetection { readonly enabled = true; readonly scanner: SecretScanner; readonly inputs: InputValues | undefined; - /** - * The live allowances for an accepted reply's exact copies. - * - * The same object the journal gate closes over, so a grant added here is - * one this execution's own gate consults — and nothing a document binds - * under the policy's name can add to or read from it. - */ - readonly grants: Set; - constructor( - scanner: SecretScanner, - inputs: InputValues | undefined, - grants: Set, - ) { + constructor(scanner: SecretScanner, inputs: InputValues | undefined) { super(); this.scanner = scanner; this.inputs = inputs; - this.grants = grants; Object.freeze(this); } } @@ -390,6 +378,7 @@ export function* useSecretDetection( requested: boolean | undefined, stream: DurableStream, inputs?: InputValues, + grants = new Set(), ): Operation { const original = stream; if (inputs !== undefined) { @@ -423,8 +412,7 @@ export function* useSecretDetection( const create = (yield* CurrentScannerFactory.get()) ?? createSecretScanner; const scanner = create(); - const grants = new Set(); - yield* CurrentDetection.set(new EnabledDetection(scanner, inputs, grants)); + yield* CurrentDetection.set(new EnabledDetection(scanner, inputs)); return { journal: guardWithSecretDetection(stream, scanner, grants), disclose: projectedDisclosure(discloseThrough(scanner)), @@ -451,7 +439,7 @@ export interface SecretDetection { readonly journal: DurableStream; readonly disclose: SecretDisclosure; readonly checkReplyText: ReplyTextCheck; - allowReplyCopies(grant: ReplyCopyGrant): () => void; + allowReplyCopies(grant: AppendGrant): () => void; } export type ReplyTextCheck = (text: string, copies: readonly ApprovedMatch[]) => Operation; @@ -559,7 +547,7 @@ function discloseThrough(scanner: SecretScanner): SecretDisclosure { function guardWithSecretDetection( stream: DurableStream, scanner: SecretScanner, - grants: ReadonlySet, + grants: ReadonlySet, ): DurableStream { const guarded = guardDurableStream(stream, function* (event) { const serialized = serializeDurableEvent(event); @@ -592,33 +580,13 @@ function guardWithSecretDetection( return false; } const spans = yield* locateSecrets(scanner, serialized); - if (spans === undefined || spans.length !== count) { + if (spans === undefined || spans.length !== count || !grants.has(claiming)) { return false; } return claiming.admits(event, serialized, spans); } } -/** - * Add one allowance for an accepted reply's exact copies to this execution's - * own gate, and answer how to retire it. - * - * Core-private: only the held conversation that accepted the reply adds one, - * from inside the execution whose gate it changes. Outside an execution, or - * where detection is off, nothing is added — off already admits everything, - * and a missing policy admits nothing. - */ -export function* grantReplyCopies(grant: ReplyCopyGrant): Operation<() => void> { - const detection = yield* currentDetection(); - if (!(detection instanceof EnabledDetection)) { - return () => {}; - } - detection.grants.add(grant); - return () => { - detection.grants.delete(grant); - }; -} - /** * Where this execution's scanner finds credentials in one completed reply, in * the reply's own coordinates — or nothing when it cannot say exactly. diff --git a/packages/core/src/secrets/reply-grant.ts b/packages/core/src/secrets/reply-grant.ts index 6f5eda782..6221a9dc1 100644 --- a/packages/core/src/secrets/reply-grant.ts +++ b/packages/core/src/secrets/reply-grant.ts @@ -1,26 +1,7 @@ /** - * The closed exception secret detection makes for one accepted Sidekick reply. - * - * A held conversation that withheld a completed reply may ask its trusted - * foreground host whether to keep it. When the person accepts, the reply's - * exact bytes are no longer something the journal must refuse — but only - * where those bytes really are that reply: its acceptance record, the - * evaluation of exactly that source, the question choices that source wrote - * and the answer selected from them, and the one feedback turn that carries - * that answer back. Anywhere else the same value is a new finding. - * - * So a grant is not a switch and not a fingerprint list. Each one names one - * event — by the coroutine, effect type and durable name its owner is about to - * append — and the exact string fields of that event that may hold an - * approved match. The gate scans the whole serialized event as always. Every - * finding must then translate, through the event's actual serialization, into - * one of those fields at a position the grant can account for, with the same - * rule, message and bytes. One finding anywhere else, or one the grant cannot - * place, and the event is refused exactly as it would have been. - * - * Nothing here is durable, rendered or reachable from a document: the grants - * live in the execution's own detection, beside its scanner, and are added - * and retired only by the conversation that accepted the reply. + * Provenance of an accepted reply through generated evaluation and feedback. + * Each allowance accounts for a finding in a particular durable event using + * its authored source range or a choice carried from an acknowledged answer. */ import type { DurableEvent } from "@executablemd/durable-streams"; @@ -30,12 +11,10 @@ import type { SourceRange } from "../document-targets.ts"; import { isJsonObject } from "../json.ts"; import { secretInputFields } from "./input-schema.ts"; import type { SecretSpan } from "./scanner.ts"; - -/** One approved match, in the coordinates of the reply it was found in. */ -export interface ApprovedMatch extends SecretSpan { - /** The exact matched bytes, held only in memory for the life of the grant. */ - readonly bytes: string; -} +import type { AppendGrant as ReplyCopyGrant } from "./append-approval.ts"; +import { encodedOffset, exactly, place, within } from "./secret-placement.ts"; +import type { ApprovedMatch, Path } from "./secret-placement.ts"; +export type { ApprovedMatch } from "./secret-placement.ts"; /** A value the evaluation's own question answered with, carried to feedback. */ export interface FeedbackSlice extends SourceRange { @@ -59,59 +38,6 @@ export interface ElicitChoiceSelection { readonly option: number; } -/** One live allowance, as the gate asks it. */ -export interface ReplyCopyGrant { - published?(event: DurableEvent): void; - /** - * Whether this grant speaks for `event` at all. - * - * Exactly one grant may speak for an event; one that does not leaves it to - * the next, and an event no grant speaks for is refused on any finding. - */ - claims(event: DurableEvent): boolean; - /** Whether every span the scanner found in `serialized` is accounted for. */ - admits(event: DurableEvent, serialized: string, spans: readonly SecretSpan[]): boolean; -} - -/** The acceptance record of one withheld turn, and nothing else. */ -export function acceptanceGrant(input: { - readonly type: string; - readonly name: string; - readonly text: string; - readonly approved: readonly ApprovedMatch[]; -}): ReplyCopyGrant { - let used = false; - return { - claims(event) { - return ( - !used && - event.type === "yield" && - event.coroutineId === "root" && - event.description.type === input.type && - event.description.name === input.name - ); - }, - admits(event, serialized, spans) { - used = true; - if (event.type !== "yield" || event.result.status !== "ok") { - return false; - } - const value = event.result.value; - if (!isJsonObject(value) || value.text !== input.text) { - return false; - } - const placed = place(serialized, [["result", "value", "text"]]); - return ( - placed !== undefined && - spans.every((span) => { - const at = within(placed, span); - return at !== undefined && exactly(input.approved, span, at.start, at.end); - }) - ); - }, - }; -} - /** * One evaluation of exactly the accepted source. * @@ -406,172 +332,12 @@ export function carriedCopies( }); } -/** Whether one located span is exactly one approved match. */ -function exactly( - approved: readonly ApprovedMatch[], - span: SecretSpan, - start: number, - end: number, -): boolean { - return approved.some( - (one) => - one.ruleId === span.ruleId && - one.messageId === span.messageId && - one.start === start && - one.end === end, - ); -} - -type Path = readonly (string | number)[]; - interface Leaf { readonly path: Path; readonly origin: number; readonly answerField?: string; } -/** One string field, where the event's serialization holds its literal. */ -interface Placed { - readonly value: string; - /** Offset of the literal's opening quote in the serialized event. */ - readonly at: number; - /** For each content offset of the literal, the value index it begins, or -1. */ - readonly boundaries: Map; - readonly length: number; -} - -/** - * Where each named string field sits in this exact serialization. - * - * Found by serializing the same event with each field replaced by a unique - * marker and then putting the real literals back: what that reconstructs must - * be byte-identical to what the gate scanned, or nothing is placed. A field - * that is absent or not a string places nothing either. - */ -function place(serialized: string, paths: readonly Path[], indent?: number): Placed[] | undefined { - let copy: unknown; - try { - copy = JSON.parse(serialized); - } catch { - return undefined; - } - const nonce = crypto.randomUUID(); - const values: string[] = []; - for (const [index, path] of paths.entries()) { - const parent = walk(copy, path.slice(0, -1)); - const key = path[path.length - 1]; - if (parent === undefined || key === undefined) { - return undefined; - } - const value = (parent as Record)[key]; - if (typeof value !== "string") { - return undefined; - } - values.push(value); - (parent as Record)[key] = `\u0001${nonce}:${index}\u0001`; - } - const marked = `${JSON.stringify(copy, null, indent)}\n`; - const located = values - .map((value, index) => { - const marker = JSON.stringify(`\u0001${nonce}:${index}\u0001`); - const at = marked.indexOf(marker); - return { index, value, at, marker }; - }) - .sort((a, b) => a.at - b.at); - if (located.some((one) => one.at < 0)) { - return undefined; - } - let rebuilt = ""; - let cursor = 0; - const placed: Placed[] = new Array(values.length); - for (const one of located) { - rebuilt += marked.slice(cursor, one.at); - const literal = JSON.stringify(one.value); - const boundaries = boundariesOf(one.value); - if (boundaries === undefined) { - return undefined; - } - placed[one.index] = { - value: one.value, - at: rebuilt.length, - boundaries, - length: literal.length, - }; - rebuilt += literal; - cursor = one.at + one.marker.length; - } - rebuilt += marked.slice(cursor); - return rebuilt === serialized ? placed : undefined; -} - -function encodedOffset(field: Placed | undefined, index: number): number | undefined { - if (field === undefined) { - return undefined; - } - for (const [offset, unit] of field.boundaries) { - if (unit === index) { - return field.at + 1 + offset; - } - } - return undefined; -} - -/** Translate one serialized span into a field's own value coordinates. */ -function within( - placed: readonly Placed[], - span: SecretSpan, -): { leaf: number; value: string; start: number; end: number } | undefined { - for (const [leaf, one] of placed.entries()) { - if (span.start <= one.at || span.end >= one.at + one.length) { - continue; - } - const start = one.boundaries.get(span.start - one.at - 1); - const end = one.boundaries.get(span.end - one.at - 1); - if (start === undefined || end === undefined || start < 0 || end < 0) { - return undefined; - } - return { leaf, value: one.value, start, end }; - } - return undefined; -} - -/** - * Each content offset of `JSON.stringify(value)` that begins a code unit of - * `value`, mapped to that unit's index — with the end of the value mapped to - * its length. Offsets inside an escape sequence or between the halves of a - * surrogate pair are not boundaries. - */ -export function boundariesOf(value: string): Map | undefined { - const boundaries = new Map(); - let offset = 0; - for (let index = 0; index < value.length; ) { - const code = value.charCodeAt(index); - let width = 1; - if (code >= 0xd800 && code <= 0xdbff && index + 1 < value.length) { - const next = value.charCodeAt(index + 1); - if (next >= 0xdc00 && next <= 0xdfff) { - width = 2; - } - } - boundaries.set(offset, index); - offset += JSON.stringify(value.slice(index, index + width)).length - 2; - index += width; - } - boundaries.set(offset, value.length); - return offset === JSON.stringify(value).length - 2 ? boundaries : undefined; -} - -function walk(value: unknown, path: Path): object | undefined { - let current: unknown = value; - for (const key of path) { - if (current === null || typeof current !== "object") { - return undefined; - } - current = (current as Record)[key]; - } - return current !== null && typeof current === "object" ? current : undefined; -} - /** The approved matches of one reply, from the spans its own scan located. */ export function approvedMatches(text: string, spans: readonly SecretSpan[]): ApprovedMatch[] { return spans.map((span) => Object.freeze({ ...span, bytes: text.slice(span.start, span.end) })); diff --git a/packages/core/src/secrets/secret-placement.ts b/packages/core/src/secrets/secret-placement.ts new file mode 100644 index 000000000..9285bc506 --- /dev/null +++ b/packages/core/src/secrets/secret-placement.ts @@ -0,0 +1,171 @@ +import type { SecretSpan } from "./scanner.ts"; + +/** One approved match, in the coordinates of the field it was found in. */ +export interface ApprovedMatch extends SecretSpan { + /** The exact matched bytes, held only in memory for the life of the approval. */ + readonly bytes: string; +} + +/** Whether one located span is exactly one approved match. */ +export function exactly( + approved: readonly SecretSpan[], + span: SecretSpan, + start: number, + end: number, +): boolean { + return approved.some( + (one) => + one.ruleId === span.ruleId && + one.messageId === span.messageId && + one.start === start && + one.end === end, + ); +} + +export type Path = readonly (string | number)[]; + +/** One string field, where the event's serialization holds its literal. */ +interface Placed { + readonly value: string; + /** Offset of the literal's opening quote in the serialized event. */ + readonly at: number; + /** For each content offset of the literal, the value index it begins, or -1. */ + readonly boundaries: Map; + readonly length: number; +} + +/** + * Where each named string field sits in this exact serialization. + * + * Found by serializing the same event with each field replaced by a unique + * marker and then putting the real literals back: what that reconstructs must + * be byte-identical to what the gate scanned, or nothing is placed. A field + * that is absent or not a string places nothing either. + */ +export function place( + serialized: string, + paths: readonly Path[], + indent?: number, +): Placed[] | undefined { + let copy: unknown; + try { + copy = JSON.parse(serialized); + } catch { + return undefined; + } + const nonce = crypto.randomUUID(); + const values: string[] = []; + for (const [index, path] of paths.entries()) { + const parent = walk(copy, path.slice(0, -1)); + const key = path[path.length - 1]; + if (parent === undefined || key === undefined || !Object.hasOwn(parent, key)) { + return undefined; + } + const value = (parent as Record)[key]; + if (typeof value !== "string") { + return undefined; + } + values.push(value); + (parent as Record)[key] = `\u0001${nonce}:${index}\u0001`; + } + const marked = `${JSON.stringify(copy, null, indent)}\n`; + const located = values + .map((value, index) => { + const marker = JSON.stringify(`\u0001${nonce}:${index}\u0001`); + const at = marked.indexOf(marker); + return { index, value, at, marker }; + }) + .sort((a, b) => a.at - b.at); + if (located.some((one) => one.at < 0)) { + return undefined; + } + let rebuilt = ""; + let cursor = 0; + const placed: Placed[] = new Array(values.length); + for (const one of located) { + rebuilt += marked.slice(cursor, one.at); + const literal = JSON.stringify(one.value); + const boundaries = boundariesOf(one.value); + if (boundaries === undefined) { + return undefined; + } + placed[one.index] = { + value: one.value, + at: rebuilt.length, + boundaries, + length: literal.length, + }; + rebuilt += literal; + cursor = one.at + one.marker.length; + } + rebuilt += marked.slice(cursor); + return rebuilt === serialized ? placed : undefined; +} + +export function encodedOffset(field: Placed | undefined, index: number): number | undefined { + if (field === undefined) { + return undefined; + } + for (const [offset, unit] of field.boundaries) { + if (unit === index) { + return field.at + 1 + offset; + } + } + return undefined; +} + +/** Translate one serialized span into a field's own value coordinates. */ +export function within( + placed: readonly Placed[], + span: SecretSpan, +): { leaf: number; value: string; start: number; end: number } | undefined { + for (const [leaf, one] of placed.entries()) { + if (span.start <= one.at || span.end >= one.at + one.length) { + continue; + } + const start = one.boundaries.get(span.start - one.at - 1); + const end = one.boundaries.get(span.end - one.at - 1); + if (start === undefined || end === undefined || start < 0 || end < 0) { + return undefined; + } + return { leaf, value: one.value, start, end }; + } + return undefined; +} + +/** + * Each content offset of `JSON.stringify(value)` that begins a code unit of + * `value`, mapped to that unit's index — with the end of the value mapped to + * its length. Offsets inside an escape sequence or between the halves of a + * surrogate pair are not boundaries. + */ +export function boundariesOf(value: string): Map | undefined { + const boundaries = new Map(); + let offset = 0; + for (let index = 0; index < value.length; ) { + const code = value.charCodeAt(index); + let width = 1; + if (code >= 0xd800 && code <= 0xdbff && index + 1 < value.length) { + const next = value.charCodeAt(index + 1); + if (next >= 0xdc00 && next <= 0xdfff) { + width = 2; + } + } + boundaries.set(offset, index); + offset += JSON.stringify(value.slice(index, index + width)).length - 2; + index += width; + } + boundaries.set(offset, value.length); + return offset === JSON.stringify(value).length - 2 ? boundaries : undefined; +} + +function walk(value: unknown, path: Path): object | undefined { + let current: unknown = value; + for (const key of path) { + if (current === null || typeof current !== "object" || !Object.hasOwn(current, key)) { + return undefined; + } + current = (current as Record)[key]; + } + return current !== null && typeof current === "object" ? current : undefined; +} diff --git a/packages/core/tests/append-approval.test.ts b/packages/core/tests/append-approval.test.ts new file mode 100644 index 000000000..9e07484a9 --- /dev/null +++ b/packages/core/tests/append-approval.test.ts @@ -0,0 +1,151 @@ +import { describe, it } from "@executablemd/test-support/bdd"; +import { expect } from "@executablemd/test-support/expect"; +import { scoped, withResolvers } from "effection"; +import type { Operation } from "effection"; +import { createDurableOperation, InMemoryStream } from "@executablemd/durable-streams"; +import type { Json } from "@executablemd/durable-streams"; +import { executeInstalledWithApprovals } from "../host.ts"; +import type { AppendApproval, AppendApprovals, ExecutionInstallation } from "../host.ts"; +import { retainedSource } from "../mod.ts"; +import { useSecretScannerFactory } from "../src/secrets/policy.ts"; +import { createScannerWith } from "../src/secrets/scanner.ts"; + +const marker = "synthetic-marker"; +const text = `private note\n${marker}`; +const description = { type: "host_note", name: "keep" }; +const match = { + ruleId: "test-word", + messageId: "marker", + start: text.indexOf(marker), + end: text.length, +}; +const approval: AppendApproval = { + coroutineId: "root", + ...description, + fields: [{ path: ["result", "value", "note"], text, matches: [match] }], +}; + +function* useMarkerDetector(): Operation { + yield* useSecretScannerFactory(() => + createScannerWith((input) => { + const messages = Array.from(input.matchAll(/synthetic-marker/g), ({ index }) => { + const range: [number, number] = [index, index + marker.length]; + return { ruleId: match.ruleId, messageId: match.messageId, range }; + }); + return Promise.resolve({ messages }); + }), + ); +} + +function* openNote(stream: InMemoryStream, body: (approvals: AppendApprovals) => Operation) { + const bridge = withResolvers(); + const installation: ExecutionInstallation = { + components: [ + { + name: "NoteHost", + origin: "@test/note", + props: { type: "object", properties: {}, additionalProperties: false }, + description: "Publish the note this host owns.", + factory: () => + function* (): Operation { + const approvals = yield* bridge.operation; + yield* body(approvals); + return ""; + }, + }, + ], + }; + const { execution, approvals } = yield* executeInstalledWithApprovals( + { ...retainedSource("host-note.md", "\n"), stream }, + [installation], + ); + expect(execution).not.toHaveProperty("approvals"); + bridge.resolve(approvals); + return yield* execution; +} + +function* publish(record: Json, onLive?: () => void): Operation { + return yield createDurableOperation( + description, + // deno-lint-ignore require-yield + function* (): Operation { + onLive?.(); + return record; + }, + ); +} + +function notes(stream: InMemoryStream) { + return stream + .snapshot() + .flatMap((event) => + event.type === "yield" && event.description.type === description.type ? [event.result] : [], + ); +} + +describe("a trusted host's append approval", () => { + it("commits an exact note and replays it without granting or executing again", function* () { + yield* useMarkerDetector(); + const stream = new InMemoryStream(); + let wrote = 0; + const result = yield* openNote(stream, (approvals) => + scoped(function* () { + yield* approvals.approveAppend(approval); + yield* publish({ note: text }, () => { + wrote++; + }); + }), + ); + expect(result.ok).toBe(true); + expect(notes(stream)).toEqual([{ status: "ok", value: { note: text } }]); + + const replayed = yield* openNote(stream, function* () { + expect( + yield* publish({ note: "" }, () => { + wrote++; + }), + ).toEqual({ note: text }); + }); + expect(replayed.ok).toBe(true); + expect(wrote).toBe(1); + }); + + it("retires the approval with its scope and leaves other fields subject to the scanner", function* () { + yield* useMarkerDetector(); + const expired = new InMemoryStream(); + const afterScope = yield* openNote(expired, function* (approvals) { + yield* scoped(() => approvals.approveAppend(approval)); + yield* publish({ note: text }); + }); + expect(afterScope.ok).toBe(false); + expect(notes(expired)).toEqual([]); + + const unexpected = new InMemoryStream(); + const extraField = yield* openNote(unexpected, function* (approvals) { + yield* approvals.approveAppend(approval); + yield* publish({ note: text, other: marker }); + }); + expect(extraField.ok).toBe(false); + expect(notes(unexpected)).toEqual([]); + + const changed = new InMemoryStream(); + const changedText = yield* openNote(changed, function* (approvals) { + yield* approvals.approveAppend(approval); + yield* publish({ note: text.replace("private", "altered") }); + }); + expect(changedText.ok).toBe(false); + expect(notes(changed)).toEqual([]); + }); + + it("consumes the approval after one append even within the same scope", function* () { + yield* useMarkerDetector(); + const stream = new InMemoryStream(); + const result = yield* openNote(stream, function* (approvals) { + yield* approvals.approveAppend(approval); + yield* publish({ note: text }); + yield* publish({ note: text }); + }); + expect(result.ok).toBe(false); + expect(notes(stream)).toEqual([{ status: "ok", value: { note: text } }]); + }); +}); From 526c43df60e5c8055451a690149ba276c4fd35d5 Mon Sep 17 00:00:00 2001 From: Taras Mankovski Date: Sun, 15 Nov 2026 13:28:49 -0500 Subject: [PATCH 2/6] Move reply continuation above Core evaluation --- packages/core/host.ts | 12 +- packages/core/mod.ts | 7 +- packages/core/src/agent/components.ts | 17 +- packages/core/src/agent/conversation.ts | 221 +++++++++--------- packages/core/src/agent/journal.ts | 36 ++- packages/core/src/agent/reply-acceptance.ts | 2 +- packages/core/src/agent/reply-review.ts | 17 +- ...-grant.ts => approved-generated-source.ts} | 176 ++++---------- packages/core/src/component-documentation.ts | 48 ---- packages/core/src/execute.ts | 99 +++++--- packages/core/src/expand.ts | 6 +- packages/core/src/generated-root-owner.ts | 98 ++++++-- packages/core/src/generated-xmd.ts | 27 +-- packages/core/src/secrets/append-approval.ts | 1 - packages/core/src/secrets/policy.ts | 78 +++---- packages/core/tests/append-approval.test.ts | 102 +++++++- specs/executable-mdx-spec.md | 13 +- 17 files changed, 516 insertions(+), 444 deletions(-) rename packages/core/src/{secrets/reply-grant.ts => approved-generated-source.ts} (61%) diff --git a/packages/core/host.ts b/packages/core/host.ts index f5b86f07d..4dd5b5f0f 100644 --- a/packages/core/host.ts +++ b/packages/core/host.ts @@ -320,7 +320,15 @@ export type { GeneratedXmdRequest, GeneratedXmdRootResult, } from "./src/generated-xmd.ts"; -export type { HostExecution } from "./src/execute.ts"; +export type { ExecutionApprovals, HostExecution } from "./src/execute.ts"; +export type { + ApprovedGeneratedXmdEvaluation, + GeneratedSourceApproval, +} from "./src/generated-root-owner.ts"; +export type { + ApprovedElicitAnswer, + ElicitChoiceSelection, +} from "./src/approved-generated-source.ts"; export { HostExecutionError } from "./src/generated-root-owner.ts"; export { AgentConversationError, @@ -432,7 +440,7 @@ export type { AgentReplyHold, AgentReplyReviewer, } from "./src/agent/reply-review.ts"; -export type { FeedbackSlice } from "./src/secrets/reply-grant.ts"; +export type { FeedbackSlice } from "./src/agent/reply-review.ts"; /** * `` as detached configuration, for the host that installs it. diff --git a/packages/core/mod.ts b/packages/core/mod.ts index ad50b083e..5370ca4bb 100644 --- a/packages/core/mod.ts +++ b/packages/core/mod.ts @@ -236,11 +236,8 @@ export type { SelectedEntry } from "./src/syntax-markdown.ts"; * lookup rather than two that agree by hand: the command reaches the index and * the selection core's own component reaches. */ -export { - agentDocumentation, - documentationIndexFor, - packageDocumentation, -} from "./src/component-documentation.ts"; +export { documentationIndexFor, packageDocumentation } from "./src/component-documentation.ts"; +export { agentDocumentation } from "./src/agent/components.ts"; export type { DocumentationContribution, DocumentationReader, diff --git a/packages/core/src/agent/components.ts b/packages/core/src/agent/components.ts index b2b7c61f7..69f486ebf 100644 --- a/packages/core/src/agent/components.ts +++ b/packages/core/src/agent/components.ts @@ -26,7 +26,8 @@ import type { Operation, Result } from "effection"; import { Execution } from "../execute.ts"; import { registerComponents } from "../components/registration.ts"; import { contributeDocumentation } from "../documentation-api.ts"; -import { agentDocumentation } from "../component-documentation.ts"; +import { packageDocumentation, packagedAssetReader } from "../component-documentation.ts"; +import type { DocumentationContribution, DocumentationReader } from "../component-documentation.ts"; import { CORE_ORIGIN } from "../components/registry.ts"; import { createReplayStream } from "../replay-stream.ts"; import { documented } from "../components/documentation.ts"; @@ -209,6 +210,20 @@ export const AGENT_REGISTRATIONS: readonly ComponentRegistration[] = [ }, ]; +export function agentDocumentation( + read: DocumentationReader = packagedAssetReader, +): Operation { + return packageDocumentation( + new URL("./components.md", import.meta.url), + { owner: CORE_ORIGIN, asset: "packages/core/src/agent/components.md" }, + [ + ...AGENT_REGISTRATIONS.map((registration) => registration.name), + ...agentIdentityComponents().map((component) => component.name), + ], + read, + ); +} + /** * The agent vocabulary, as declarations and nothing else. * diff --git a/packages/core/src/agent/conversation.ts b/packages/core/src/agent/conversation.ts index 77af235c3..cb6ac2fdc 100644 --- a/packages/core/src/agent/conversation.ts +++ b/packages/core/src/agent/conversation.ts @@ -82,33 +82,17 @@ import type { Json as DurableJson, } from "@executablemd/durable-streams"; -import { executeInstalledBound } from "../execute.ts"; -import type { BoundExecution, ExecutionInstallation } from "../execute.ts"; -import type { AppendApprovals } from "../secrets/append-approval.ts"; -import type { BoundRootEvaluator } from "../generated-root-owner.ts"; -import type { - AcceptedRootReply, - GeneratedXmdRequest, - GeneratedXmdRootResult, -} from "../generated-xmd.ts"; +import { executeInstalledWithApprovals } from "../execute.ts"; +import type { ExecutionApprovals, ExecutionInstallation, HostExecution } from "../execute.ts"; +import type { ApprovedElicitAnswer } from "../approved-generated-source.ts"; +import type { GeneratedXmdRequest, GeneratedXmdRootResult } from "../generated-xmd.ts"; import { durabilityFailure } from "../errors.ts"; import { isJsonObject, parseJson } from "../json.ts"; import { retainedSource } from "../root-source.ts"; -import { - captureReplyTextCheck, - locateReplySecrets, - scanSecrets, - secretPolicy, -} from "../secrets/policy.ts"; -import type { ReplyTextCheck } from "../secrets/policy.ts"; -import { - approvedMatches, - carriedCopies, - evaluationGrant, - feedbackGrant, -} from "../secrets/reply-grant.ts"; -import type { ApprovedMatch, FeedbackSlice } from "../secrets/reply-grant.ts"; +import { encodedOffset, place } from "../secrets/secret-placement.ts"; +import type { ApprovedMatch } from "../secrets/secret-placement.ts"; import type { SecretSpan } from "../secrets/scanner.ts"; +import type { FeedbackSlice } from "./reply-review.ts"; import { AgentConversationProvider } from "./conversation-provider.ts"; import type { AgentOptions, @@ -333,7 +317,7 @@ interface Live { * ending names one outcome. */ fatal?: Error; - checkReplyText?: ReplyTextCheck; + approvals?: ExecutionApprovals; /** * What an accepted reply may still carry, for the very next job only. * @@ -354,11 +338,13 @@ type Accepted = readonly approved: readonly ApprovedMatch[]; readonly hold: AgentReplyHold; } + | { + readonly kind: "selecting"; + readonly hold: AgentReplyHold; + } | { readonly kind: "feedback"; - readonly select: ReturnType["select"]; - /** What the evaluation's own question selected, read when the turn starts. */ - readonly carried: ReturnType["carried"]; + readonly answers: readonly ApprovedElicitAnswer[]; readonly hold: AgentReplyHold; registered?: { readonly text: string; readonly slices: readonly FeedbackSlice[] }; }; @@ -520,11 +506,11 @@ function handle( return { *checkSidekickText(text): Operation> { - if (!live.open || live.checkReplyText === undefined) { + if (!live.open || live.approvals === undefined) { return Err(ended()); } try { - yield* live.checkReplyText(text, []); + yield* live.approvals.clearText(text, []); return live.open ? Ok(undefined) : Err(ended()); } catch (error) { return Err(error instanceof Error ? error : new AgentConversationError(String(error))); @@ -672,7 +658,10 @@ function handle( }; } -type ConversationBinding = Omit; +interface ConversationBinding { + readonly execution: HostExecution; + readonly approvals: ExecutionApprovals; +} /** * Run the conversation's own durable root, and serve turns inside it forever. @@ -739,7 +728,7 @@ function* serve( ], }; try { - const { execution, ...binding } = yield* executeInstalledBound( + const binding = yield* executeInstalledWithApprovals( { ...retainedSource(CONVERSATION_ROOT_PATH, CONVERSATION_ROOT_SOURCE), stream: request.history, @@ -750,7 +739,7 @@ function* serve( // Before the completion is waited on, and after the handle exists: the // element is suspended on this, and nothing it does decides whether this // resolves. - const settled = yield* execution; + const settled = yield* binding.execution; if (!settled.ok && durabilityFailure(settled.error) !== undefined) { live.fatal ??= settled.error; } @@ -844,9 +833,7 @@ function* held( // conversation is announced: a handle that reported itself ready and then // refused to evaluate would be ready for two of the three things it offers. const binding = yield* bridge.operation; - const { evaluate } = binding; - const checkReplyText = yield* captureReplyTextCheck(); - live.checkReplyText = checkReplyText; + live.approvals = binding.approvals; announce(Ok(undefined)); while (true) { const next = yield* jobs.next(); @@ -869,16 +856,17 @@ function* held( job.accepted === offered.hold && job.request.source === offered.text ) { - yield* evaluatedAccepted(evaluate, live, job, offered); + yield* evaluated(binding, live, job, offered); } else { - yield* evaluated(evaluate, live, job); + yield* evaluated(binding, live, job); } continue; } - const carried = offered?.kind === "feedback" ? offered.carried() : []; - const carrying = - offered?.kind === "feedback" && offered.registered?.text === job.input && carried.length > 0 - ? { carried, slices: offered.registered.slices } + const copies = + offered?.kind === "feedback" && + offered.registered?.text === job.input && + offered.answers.length > 0 + ? feedbackCopies(job.input, offered.registered.slices, offered.answers) : undefined; const observed: Observed = {}; yield* deliver( @@ -893,9 +881,8 @@ function* held( used, sessionFacts(active, established, placement), live, - carrying, - checkReplyText, - binding, + copies, + binding.approvals, ); if (live.fatal !== undefined) { yield* suspend(); @@ -1135,17 +1122,13 @@ function deliver( used: boolean, facts: SessionFacts, live: Live, - carrying: Carrying | undefined, - checkReplyText: ReplyTextCheck, - bound: Pick, + copies: readonly ApprovedMatch[] | undefined, + approvals: ExecutionApprovals, ): Operation { // Scoped, so the turn cannot outlive the call that asked for it however this // returns: a turn still running would hold its durable operation open, and // the next turn would be a second one open on the same sequence. return scoped(function* () { - const copies = - carrying === undefined ? [] : carriedCopies(job.input, carrying.slices, carrying.carried); - const prepare = (delegated: string) => (delegated.startsWith(job.input) ? copies : []); // Registered *before* the turn is spawned, which is what makes it the last // thing to unwind: cleanups registered later run first, so the turn — and // every cleanup the provider registered inside it — has finished by the @@ -1154,17 +1137,6 @@ function deliver( yield* ensure(() => { job.joined.resolve(); }); - // The one turn an accepted answer may be carried by, for exactly as long as - // this turn runs: retired when it commits, fails or is cancelled. - if (carrying !== undefined) { - yield* bound.registerGrant( - feedbackGrant({ - type: AGENT_PROMPT, - name: turnName(order), - prepare, - }), - ); - } const turn = yield* spawn(() => conversationTurn( provider, @@ -1178,10 +1150,9 @@ function deliver( used, facts, live, - bound.approvals, - job.automaticFeedback || carrying !== undefined - ? (delegated) => checkReplyText(delegated, prepare(delegated)) - : undefined, + approvals, + copies ?? [], + job.automaticFeedback || copies !== undefined, ), ); const outcome = yield* race([ @@ -1245,8 +1216,9 @@ function conversationTurn( used: boolean, facts: SessionFacts, live: Live, - approvals: AppendApprovals, - checkInput: ((text: string) => Operation) | undefined, + approvals: ExecutionApprovals, + copies: readonly ApprovedMatch[], + checkFeedback: boolean, ): Operation { return (function* (): Operation { try { @@ -1322,8 +1294,12 @@ function conversationTurn( let reviewable: | { readonly text: string; readonly spans: readonly SecretSpan[] } | undefined; + const clearFeedback = checkFeedback + ? (text: string): Operation => + approvals.clearText(text, text.startsWith(job.input) ? copies : []) + : undefined; const record = yield* persistPrompt( - { name: turnName(order), input: checkInput === undefined ? job.input : "" }, + { name: turnName(order), input: checkFeedback ? "" : job.input }, // The composition this conversation installed runs above the turn's // own terminal, so the text it finally delegates is settled inside // the live runner. `retain` is the journal's own; nothing the @@ -1334,17 +1310,18 @@ function conversationTurn( agent, session, retain, - checkInput, + checkInput: clearFeedback, } satisfies DirectPromptTurn); - const kept = yield* withholdFlaggedReply(ran, established); + const kept = yield* withholdFlaggedReply(ran, established, approvals); if (kept.withheld === true) { - const spans = yield* locateReplySecrets(ran.text); + const spans = yield* approvals.locateText(ran.text); reviewable = spans === undefined ? undefined : { text: ran.text, spans }; } return kept; }, () => carried.association, () => carried.begun, + copies.length === 0 ? undefined : { approvals, text: job.input, copies }, ); // A provider may name the conversation only once the turn has started, // which is the ordinary first-turn case. Read from the record, because @@ -1412,10 +1389,37 @@ function conversationTurn( })(); } -/** What one turn may carry of an accepted reply's selected answer. */ -interface Carrying { - readonly carried: ReturnType["carried"]>; - readonly slices: readonly FeedbackSlice[]; +function feedbackCopies( + text: string, + slices: readonly FeedbackSlice[], + answers: readonly ApprovedElicitAnswer[], +): ApprovedMatch[] { + return slices.flatMap((slice) => { + const answer = answers.find( + (one) => one.coroutineId === slice.coroutineId && one.index === slice.index, + ); + if (answer === undefined) { + return []; + } + const rendered = JSON.stringify(answer.value, null, 2); + if (text.slice(slice.start, slice.end) !== rendered) { + return []; + } + const names = [...new Set(answer.copies.map(({ field }) => field))]; + const placements = place( + `${rendered}\n`, + names.map((name) => [name]), + 2, + ); + return answer.copies.flatMap(({ field, match }) => { + const placement = placements?.[names.indexOf(field)]; + const start = encodedOffset(placement, match.start); + const end = encodedOffset(placement, match.end); + return start === undefined || end === undefined || rendered.slice(start, end) !== match.bytes + ? [] + : [{ ...match, start: slice.start + start, end: slice.start + end }]; + }); + }); } /** @@ -1435,7 +1439,7 @@ function* reviewWithheld( begun: unknown, name: string, live: Live, - approvals: AppendApprovals, + approvals: ExecutionApprovals, ): Operation { const hold: { current?: AgentReplyHold } = {}; const reviewed = yield* askReplyReview({ @@ -1444,8 +1448,8 @@ function* reviewWithheld( begun, selectedElicitation(selection) { const current = live.accepted; - if (current?.kind === "feedback" && current.hold === hold.current) { - current.select(selection); + if (current?.kind === "selecting" && current.hold === hold.current) { + approvals.selectElicitation(selection); } }, carry(text, slices) { @@ -1478,7 +1482,9 @@ function* reviewWithheld( if (reviewed.decision !== "accept") { return undefined; } - const approved = approvedMatches(pending.text, pending.spans); + const approved = pending.spans.map((span) => + Object.freeze({ ...span, bytes: pending.text.slice(span.start, span.end) }), + ); yield* scoped(function* () { yield* approvals.approveAppend({ coroutineId: "root", @@ -1492,37 +1498,6 @@ function* reviewWithheld( return pending.text; } -/** - * Evaluate exactly the accepted source, with its copies granted for this one - * evaluation. - * - * The grant binds to the evaluation's own admission and coroutine and is - * retired when the evaluation joins. What its question selected from the - * accepted choices is left for the very next turn, and only that. - */ -function* evaluatedAccepted( - evaluate: BoundRootEvaluator, - live: Live, - job: EvaluateJob, - offered: Extract, -): Operation { - const grant = evaluationGrant({ - id: job.request.id, - source: offered.text, - approved: offered.approved, - }); - // Left for the next job before this one runs, so a host that registers its - // feedback the moment its evaluation answers finds it. What it can carry is - // read when that next turn starts, after this evaluation has joined. - live.accepted = { - kind: "feedback", - carried: grant.carried, - select: grant.select, - hold: offered.hold, - }; - yield* evaluated(evaluate, live, job, { grant, approved: offered.approved }); -} - /** * A completed turn's reply was withheld in full by secret detection. * @@ -1559,6 +1534,7 @@ export class AgentReplyWithheldError extends AgentConversationError { function* withholdFlaggedReply( record: PromptRecord, established: string | undefined, + approvals: ExecutionApprovals, ): Operation { if (record.status !== "completed" || record.text === "") { return record; @@ -1571,10 +1547,7 @@ function* withholdFlaggedReply( return record; } try { - if (!(yield* secretPolicy()).enabled) { - return record; - } - if ((yield* scanSecrets(JSON.stringify(record.text))).length === 0) { + if ((yield* approvals.scan(JSON.stringify(record.text))).length === 0) { return record; } } catch { @@ -1593,19 +1566,31 @@ function* withholdFlaggedReply( * to this element, so what this adds is admission and joining and nothing else. */ function evaluated( - evaluate: BoundRootEvaluator, + binding: ConversationBinding, live: Live, job: EvaluateJob, - accepted?: AcceptedRootReply, + accepted?: Extract, ): Operation { return scoped(function* () { yield* ensure(() => { job.joined.resolve(); }); + if (accepted !== undefined) { + live.accepted = { kind: "selecting", hold: accepted.hold }; + } const served = yield* race([ (function* (): Operation { try { - return { kind: "settled", settled: { value: yield* evaluate(job.request, accepted) } }; + if (accepted === undefined) { + const value = yield* binding.execution.evaluateGeneratedXmdRoot(job.request); + return { kind: "settled", settled: { value } }; + } + const { result, answers } = yield* binding.approvals.evaluateGeneratedXmdRoot( + job.request, + { source: accepted.text, matches: accepted.approved }, + ); + live.accepted = { kind: "feedback", hold: accepted.hold, answers }; + return { kind: "settled", settled: { value: result } }; } catch (error) { // Answered *here*, at the throw, rather than after this race has // unwound. A failure of the run raised by this execution's own @@ -1636,6 +1621,8 @@ function evaluated( ]); if (served.kind === "settled") { job.answer.resolve(served.settled); + } else { + live.accepted = undefined; } }); } diff --git a/packages/core/src/agent/journal.ts b/packages/core/src/agent/journal.ts index c41c3a8d1..91fd13d31 100644 --- a/packages/core/src/agent/journal.ts +++ b/packages/core/src/agent/journal.ts @@ -47,6 +47,8 @@ */ import { createDurableOperation, ephemeral, serializeError } from "@executablemd/durable-streams"; +import type { AppendApprovals } from "../secrets/append-approval.ts"; +import type { ApprovedMatch } from "../secrets/secret-placement.ts"; import type { ActivateDurabilityFailure, DurableStream, @@ -55,7 +57,7 @@ import type { Result as DurableResult, Workflow, } from "@executablemd/durable-streams"; -import { createContext, ensure } from "effection"; +import { createContext, ensure, scoped } from "effection"; import type { Operation, Stream } from "effection"; import { Agent } from "./agent-api.ts"; import { InvocationTeardownError } from "../invocation.ts"; @@ -515,6 +517,12 @@ function permissionDecision(outcome: PermissionOutcome): PermissionOutcome | und */ export type RetainPromptInput = (input: string) => void; +interface FeedbackApproval { + readonly approvals: AppendApprovals; + readonly text: string; + readonly copies: readonly ApprovedMatch[]; +} + export function* persistPrompt( identity: { name: string; @@ -524,6 +532,7 @@ export function* persistPrompt( live: (retain: RetainPromptInput) => Operation, association: () => AgentPromptAssociation | undefined = () => undefined, begun: () => AgentPromptHandle = () => undefined, + feedback?: FeedbackApproval, ): Workflow { const sourceOwner = yield* ephemeral(SourceOwner.get()); // Held here, and handed to nothing but the live runner below: the pending @@ -544,7 +553,7 @@ export function* persistPrompt( }), ); }, - { coordinator: promptPublication(association, begun) }, + { coordinator: promptPublication(association, begun, description, feedback) }, ); const parsed = parsePromptRecord(stored); if (!parsed) { @@ -579,6 +588,8 @@ class AgentPromptPublicationError extends Error { function promptPublication( association: () => AgentPromptAssociation | undefined, begun: () => AgentPromptHandle, + description: { type: string; name: string; input: string }, + feedback: FeedbackApproval | undefined, ): LiveDurableOperationCoordinator { return { *run( @@ -612,9 +623,26 @@ function promptPublication( result = { status: "err", error: serializeError(failure) }; } + function appendPrompt(): Operation { + if (feedback === undefined || !description.input.startsWith(feedback.text)) { + return publish(result); + } + return scoped(function* () { + yield* feedback.approvals.approveAppend({ + coroutineId: "root", + type: description.type, + name: description.name, + fields: [ + { path: ["description", "input"], text: description.input, matches: feedback.copies }, + ], + }); + yield* publish(result); + }); + } + const publisher = yield* AgentInternal.operations.promptPublisher; if (publisher === undefined) { - yield* publish(result); + yield* appendPrompt(); return result; } @@ -633,7 +661,7 @@ function promptPublication( ); } appended = true; - yield* publish(published); + yield* appendPrompt(); }, }); } catch (error) { diff --git a/packages/core/src/agent/reply-acceptance.ts b/packages/core/src/agent/reply-acceptance.ts index 75fd9f58f..0a810d044 100644 --- a/packages/core/src/agent/reply-acceptance.ts +++ b/packages/core/src/agent/reply-acceptance.ts @@ -26,7 +26,7 @@ import { createDurableOperation } from "@executablemd/durable-streams"; import type { DurableEvent, Json } from "@executablemd/durable-streams"; import { isJsonObject } from "../json.ts"; import { AGENT_PROMPT, parsePromptRecord } from "./journal.ts"; -import type { ApprovedMatch } from "../secrets/reply-grant.ts"; +import type { ApprovedMatch } from "../secrets/secret-placement.ts"; /** The durable effect an accepted reply is retained under. */ export const AGENT_PROMPT_REPLY = "agent_prompt_reply"; diff --git a/packages/core/src/agent/reply-review.ts b/packages/core/src/agent/reply-review.ts index 442134fe0..31853d0ac 100644 --- a/packages/core/src/agent/reply-review.ts +++ b/packages/core/src/agent/reply-review.ts @@ -10,7 +10,7 @@ * * The question is a contextual operation, not a callback on a request. A * trusted host installs middleware for it beside its publisher; the turn calls - * the chain with a hold Core made for this one invocation; and a decision + * the chain with a hold Agent made for this one invocation; and a decision * counts only when the middleware hands it to the terminal it was given, * together with that same hold, while the turn is still waiting on it. What a * handler returns is never read, a hold kept past its turn settles nothing, a @@ -29,7 +29,14 @@ import { ensure } from "effection"; import type { Operation } from "effection"; import type { AgentPromptHandle } from "./publication.ts"; import type { SecretSpan } from "../secrets/scanner.ts"; -import type { ElicitChoiceSelection, FeedbackSlice } from "../secrets/reply-grant.ts"; +import type { SourceRange } from "../document-targets.ts"; +import type { ElicitChoiceSelection } from "../approved-generated-source.ts"; + +/** Where feedback places an acknowledged answer from one question. */ +export interface FeedbackSlice extends SourceRange { + readonly coroutineId: string; + readonly index: number; +} /** One finding in a withheld reply, as a local reviewer may show it. */ export interface AgentReplyFinding { @@ -55,7 +62,7 @@ export type AgentReplyDecision = "accept" | "withhold"; /** * One withheld reply waiting for a local decision. * - * Made by Core for one invocation of the review and good for that invocation + * Made by Agent for one invocation of the review and good for that invocation * only. Holding one grants nothing: it is settled through the terminal the * reviewer was handed, and only while the turn is still waiting. */ @@ -75,7 +82,7 @@ export interface AgentReplyHold { * carries the answer that evaluation's own question selected. * * `text` is exactly what the host hands that turn, and `slices` are where - * in it the answer sits. Core keeps this only for the very next turn of the + * in it the answer sits. Agent keeps this only for the very next turn of the * same conversation, only when the evaluation of exactly the accepted * source selected an approved choice, and only while nothing else has run; * otherwise it answers false and grants nothing. @@ -102,7 +109,7 @@ interface ReplyReviewApi { review(hold: AgentReplyHold, decision: AgentReplyDecision | undefined): Operation; } -/** What Core knows about each hold it issued, and whether it was decided. */ +/** What Agent knows about each hold it issued, and whether it was decided. */ const REVIEW = "agent.reply-review"; const ReplyReview: Api = createApi(REVIEW, { // deno-lint-ignore require-yield diff --git a/packages/core/src/secrets/reply-grant.ts b/packages/core/src/approved-generated-source.ts similarity index 61% rename from packages/core/src/secrets/reply-grant.ts rename to packages/core/src/approved-generated-source.ts index 6221a9dc1..019ac1bad 100644 --- a/packages/core/src/secrets/reply-grant.ts +++ b/packages/core/src/approved-generated-source.ts @@ -1,32 +1,27 @@ +import type { Json } from "./types.ts"; +import type { DurableEvent } from "@executablemd/durable-streams"; +import { ELICITATION_SCHEMA_FIELD, readElicitationAnswer } from "./elicit-journal.ts"; +import { dataStringLiteral } from "./generated-expressions.ts"; +import type { SourceRange } from "./document-targets.ts"; +import { isJsonObject } from "./json.ts"; +import { secretInputFields } from "./secrets/input-schema.ts"; +import type { SecretSpan } from "./secrets/scanner.ts"; +import type { AppendGrant } from "./secrets/append-approval.ts"; +import { exactly, place, within } from "./secrets/secret-placement.ts"; +import type { ApprovedMatch, Path } from "./secrets/secret-placement.ts"; /** - * Provenance of an accepted reply through generated evaluation and feedback. - * Each allowance accounts for a finding in a particular durable event using - * its authored source range or a choice carried from an acknowledged answer. + * An acknowledged answer and the exact value ranges carried from authored choices. + * The journal coordinate identifies the question observed by the host. */ - -import type { DurableEvent } from "@executablemd/durable-streams"; -import { ELICITATION_SCHEMA_FIELD, readElicitationAnswer } from "../elicit-journal.ts"; -import { dataStringLiteral } from "../generated-expressions.ts"; -import type { SourceRange } from "../document-targets.ts"; -import { isJsonObject } from "../json.ts"; -import { secretInputFields } from "./input-schema.ts"; -import type { SecretSpan } from "./scanner.ts"; -import type { AppendGrant as ReplyCopyGrant } from "./append-approval.ts"; -import { encodedOffset, exactly, place, within } from "./secret-placement.ts"; -import type { ApprovedMatch, Path } from "./secret-placement.ts"; -export type { ApprovedMatch } from "./secret-placement.ts"; - -/** A value the evaluation's own question answered with, carried to feedback. */ -export interface FeedbackSlice extends SourceRange { +export interface ApprovedElicitAnswer { readonly coroutineId: string; readonly index: number; -} - -interface CarriedAnswer { - readonly coroutineId: string; - readonly index: number; - readonly text: string; - readonly matches: readonly ApprovedMatch[]; + readonly value: Json; + readonly copies: readonly { + readonly field: string; + readonly source: SourceRange; + readonly match: ApprovedMatch; + }[]; } export interface ElicitChoiceSelection { @@ -39,31 +34,33 @@ export interface ElicitChoiceSelection { } /** - * One evaluation of exactly the accepted source. + * Provenance for one evaluation of exactly the approved source. * * Bound on its admission record: the first `generated_xmd` admission named - * for this request whose retained source is byte-equal to the accepted reply + * for this request whose retained source is byte-equal to the approved source * fixes the evaluation's own coroutine. Afterwards the grant speaks only for * that coroutine's question records. Their schema may hold an approved match * only as an enum choice the `` element at that record's own source * position wrote, and their answer only as one of those choices, selected * whole. Anything else the evaluation journals is unaccounted for. */ -export function evaluationGrant(input: { +export function approvedGeneratedSource(input: { readonly id: string; readonly source: string; readonly approved: readonly ApprovedMatch[]; -}): ReplyCopyGrant & { +}): AppendGrant & { readonly bind: (id: string) => void; readonly schemas: Map; + readonly matches: readonly ApprovedMatch[]; readonly select: (selection: ElicitChoiceSelection) => void; - readonly carried: () => readonly CarriedAnswer[]; + readonly acknowledge: (event: DurableEvent) => void; + readonly answers: () => readonly ApprovedElicitAnswer[]; } { let coroutine: string | undefined; let admitted = false; - const carried: CarriedAnswer[] = []; + const answers: ApprovedElicitAnswer[] = []; const positions = new Map(); - let pending: CarriedAnswer | undefined; + const pending = new Map(); const schemas = new Map(); const selections = new Map>(); const admission = `generated:${input.id}`; @@ -71,6 +68,7 @@ export function evaluationGrant(input: { coroutine !== undefined && (id === coroutine || id.startsWith(`${coroutine}.`)); return { schemas, + matches: input.approved, select(selection) { if ( owns(selection.coroutineId) && @@ -81,14 +79,15 @@ export function evaluationGrant(input: { selections.set(selection.coroutineId, fields); } }, - published(event) { + acknowledge(event) { if (!owns(event.coroutineId) || event.type !== "yield") { return; } const index = positions.get(event.coroutineId) ?? 0; - if (pending?.coroutineId === event.coroutineId && pending.index === index) { - carried.push(pending); - pending = undefined; + const answer = pending.get(event.coroutineId); + if (answer?.index === index) { + answers.push(answer); + pending.delete(event.coroutineId); } positions.set(event.coroutineId, index + 1); selections.delete(event.coroutineId); @@ -96,7 +95,7 @@ export function evaluationGrant(input: { bind(id) { coroutine ??= id; }, - carried: () => Object.freeze([...carried]), + answers: () => Object.freeze([...answers]), claims(event) { if (event.type !== "yield") { return false; @@ -215,8 +214,7 @@ export function evaluationGrant(input: { if (placed === undefined) { return false; } - const found: ApprovedMatch[] = []; - const text = answer === undefined ? undefined : JSON.stringify(answer, null, 2); + const copies: ApprovedElicitAnswer["copies"][number][] = []; for (const span of spans) { const at = within(placed, span); if (at === undefined) { @@ -229,22 +227,25 @@ export function evaluationGrant(input: { ) { return false; } - if (leaf.answerField !== undefined && text !== undefined) { - const fieldPlacement = place(`${text}\n`, [[leaf.answerField]], 2)?.[0]; - const start = encodedOffset(fieldPlacement, at.start); - const end = encodedOffset(fieldPlacement, at.end); - if (start === undefined || end === undefined) { - return false; - } + if (leaf.answerField !== undefined) { const bytes = at.value.slice(at.start, at.end); - if (text.slice(start, end) !== bytes) { + if (serialized.slice(span.start, span.end) !== bytes) { return false; } - found.push({ ...span, bytes, start, end }); + copies.push({ + field: leaf.answerField, + source: { start: leaf.origin + at.start, end: leaf.origin + at.end }, + match: { ...span, bytes, start: at.start, end: at.end }, + }); } } - if (found.length > 0 && text !== undefined) { - pending = { coroutineId: event.coroutineId, index, text, matches: found }; + if (copies.length > 0 && answer !== undefined) { + pending.set(event.coroutineId, { + coroutineId: event.coroutineId, + index, + value: answer, + copies, + }); } return true; @@ -262,83 +263,8 @@ export function evaluationGrant(input: { } } -/** - * The next turn's input, where it carries the evaluation's own answer. - * - * `slices` are the host's statement of where, in the text it handed the turn, - * it placed that answer. The turn's final input must still begin with exactly - * that text, so a composition that changed it inherits nothing, and each - * finding must lie inside one slice with the bytes the evaluation's answer - * carried. - */ -export function feedbackGrant(input: { - readonly name: string; - readonly type: string; - readonly prepare: (delegated: string) => readonly ApprovedMatch[]; -}): ReplyCopyGrant { - let used = false; - return { - claims(event) { - return ( - !used && - event.type === "yield" && - event.coroutineId === "root" && - event.description.type === input.type && - event.description.name === input.name - ); - }, - admits(event, serialized, spans) { - used = true; - if (event.type !== "yield") { - return false; - } - const delegated = event.description.input; - if (typeof delegated !== "string") { - return false; - } - const copies = input.prepare(delegated); - const placed = place(serialized, [["description", "input"]]); - return ( - placed !== undefined && - spans.every((span) => { - const at = within(placed, span); - if (at === undefined) { - return false; - } - return exactly(copies, span, at.start, at.end); - }) - ); - }, - }; -} - -export function carriedCopies( - text: string, - slices: readonly FeedbackSlice[], - carried: readonly CarriedAnswer[], -): ApprovedMatch[] { - return slices.flatMap((slice) => { - const answer = carried.find( - (one) => one.coroutineId === slice.coroutineId && one.index === slice.index, - ); - if (answer === undefined || text.slice(slice.start, slice.end) !== answer.text) { - return []; - } - return answer.matches.map((match) => ({ - ...match, - start: slice.start + match.start, - end: slice.start + match.end, - })); - }); -} - interface Leaf { readonly path: Path; readonly origin: number; readonly answerField?: string; } - -/** The approved matches of one reply, from the spans its own scan located. */ -export function approvedMatches(text: string, spans: readonly SecretSpan[]): ApprovedMatch[] { - return spans.map((span) => Object.freeze({ ...span, bytes: text.slice(span.start, span.end) })); -} diff --git a/packages/core/src/component-documentation.ts b/packages/core/src/component-documentation.ts index b010b81d3..55290d20f 100644 --- a/packages/core/src/component-documentation.ts +++ b/packages/core/src/component-documentation.ts @@ -21,60 +21,12 @@ import { buildDocumentationIndex } from "./documentation-index.ts"; import type { DocumentationIndex, DocumentationSource } from "./documentation-index.ts"; import { CORE_ORIGIN, CORE_REGISTRY } from "./components/registry.ts"; import { PROTECTED_COMPONENT_NAMES } from "./components/protected.ts"; -import { AGENT_REGISTRATIONS, agentIdentityComponents } from "./agent/components.ts"; /** Where core's own documentation lives, as a URL beside this module. */ export function componentDocumentationUrl(): URL { return new URL("./components/components.md", import.meta.url); } -/** - * Where the Agent registrations' documentation lives. - * - * Beside `agent/components.ts`, which is the boundary that registers them. They - * carry core's origin, so they are core's components for the join; what makes - * them a separate file is that they are a separate registration boundary, and - * documentation belongs beside the code it documents. - */ -export function agentDocumentationUrl(): URL { - return new URL("./agent/components.md", import.meta.url); -} - -/** - * The Agent registrations' contribution, for a host that installs them. - * - * Offered rather than assumed: a run that registers no Agent components has no - * Agent components to document, and demanding their documentation would refuse - * an index for a profile that is complete without them. - */ -export function* agentDocumentation( - read: DocumentationReader = packagedAssetReader, -): Operation { - return { - source: yield* readPackagedDocumentation( - agentDocumentationUrl(), - { owner: CORE_ORIGIN, asset: "packages/core/src/agent/components.md" }, - read, - ), - supplies: agentComponentNames(), - }; -} - -/** - * Every component the Agent registration boundary supplies, by name. - * - * Built when asked rather than at module scope. The Agent bootstrap imports this - * module for its own contribution, so a module-scoped set built from - * `AGENT_REGISTRATIONS` would read that array before its own module finished - * evaluating, depending on which of the two was loaded first. - */ -function agentComponentNames(): ReadonlySet { - return new Set([ - ...AGENT_REGISTRATIONS.map((registration) => registration.name), - ...agentIdentityComponents().map((component) => component.name), - ]); -} - /** Core's documentation source, read from the package rather than the caller. */ export function* readCoreDocumentation( read: DocumentationReader = packagedAssetReader, diff --git a/packages/core/src/execute.ts b/packages/core/src/execute.ts index aaf79736c..882ae5470 100644 --- a/packages/core/src/execute.ts +++ b/packages/core/src/execute.ts @@ -192,7 +192,13 @@ import { HostExecutionError, isGeneratedRootEvent, } from "./generated-root-owner.ts"; -import type { BoundRootEvaluator, GeneratedRootOwner } from "./generated-root-owner.ts"; +import type { + ApprovedGeneratedXmdEvaluation, + BoundRootEvaluator, + GeneratedRootOwner, + GeneratedSourceApproval, +} from "./generated-root-owner.ts"; +import type { ElicitChoiceSelection } from "./approved-generated-source.ts"; import { SYNTAX_COMPONENT, SYNTAX_PROTECTED } from "./components/Syntax.ts"; import { rootSyntaxReference } from "./syntax-reference.ts"; import type { SyntaxReference } from "./syntax-reference.ts"; @@ -231,11 +237,8 @@ import type { TestHarnessInstaller } from "./test-harness.ts"; import type { CheckedFailures } from "./component-failures.ts"; import { clearsLiveOutput, useSecretDetection } from "./secrets/policy.ts"; import { useAppendApprovalOwner } from "./secrets/append-approval.ts"; -import type { - AppendApprovalOwner, - AppendApprovals, - AppendGrant, -} from "./secrets/append-approval.ts"; +import type { AppendApprovals } from "./secrets/append-approval.ts"; +import type { SecretDetection } from "./secrets/policy.ts"; import { propsEnvironment } from "./eval-env.ts"; import { liveEnvironment, validateBindingName } from "./live-env.ts"; @@ -2566,6 +2569,24 @@ export interface DocumentExecution extends Operation> { output: Stream; } +/** + * Exact publication and generated-source approvals for the host that opted in. + * + * Text observations use the scanner and protected inputs of this execution. + * A generated evaluation gets only the approved source and ranges for that + * call. Hosts use the journal coordinates on returned answers to identify + * their own questions; the receipts carry no authority to append. + */ +export interface ExecutionApprovals + extends AppendApprovals, Pick { + evaluateGeneratedXmdRoot( + request: GeneratedXmdRequest, + approval: GeneratedSourceApproval, + ): Operation; + /** Attribute a host-observed selection to the active approved evaluation. */ + selectElicitation(selection: ElicitChoiceSelection): void; +} + /** * The same execution, as the trusted host that assembled it holds it. * @@ -2977,6 +2998,13 @@ function* executeDocument( const inputs = yield* inputValues(); const computed = yield* useComputedBindings(inputs); const approvalOwner = yield* useAppendApprovalOwner(); + let activeDetection: SecretDetection | undefined; + function detectionOfExecution(): SecretDetection { + if (activeDetection === undefined) { + throw new HostExecutionError("this execution has no live text policy"); + } + return activeDetection; + } const registry = createModifierRegistry(); // Held by identity as well as by name: a bound block is authorized against @@ -3263,6 +3291,9 @@ function* executeDocument( // root component import is already behind the gate. What comes back is // the stream to journal through; the policy itself stays inside the // execution that owns it. + yield* ensure(() => { + activeDetection = undefined; + }); const detection = yield* useSecretDetection( secretDetection, stream, @@ -3275,6 +3306,7 @@ function* executeDocument( // journal gate closes over rather than by whatever Context is installed // by then. computed.adopt(detection.disclose); + activeDetection = detection; // The three values a generated root is evaluated under, handed over here // by value and reaching the public handle only as one bound operation. @@ -3374,7 +3406,7 @@ function* executeDocument( reference: derivedSyntax, live: profile.live, }); - roots.supply({ journal, evaluator: bound }); + roots.supply({ journal, evaluator: bound, approvals: approvalOwner }); // The journal is wrapped before it reaches `durableRun`, so the identity // check happens inside the read that every phase downstream depends on @@ -3643,8 +3675,23 @@ function* executeDocument( }, output: channel, }, - evaluateGeneratedXmdRoot: roots.evaluate, - approvalOwner, + *evaluateGeneratedXmdRoot(request) { + return (yield* roots.evaluate(request)).result; + }, + approvals: { + ...approvalOwner.approvals, + evaluateGeneratedXmdRoot: roots.evaluate, + selectElicitation: roots.selectElicitation, + *clearText(text, copies) { + yield* detectionOfExecution().clearText(text, copies); + }, + *locateText(text) { + return yield* detectionOfExecution().locateText(text); + }, + *scan(text) { + return yield* detectionOfExecution().scan(text); + }, + }, evaluation: roots.completion, computed, stop: stopDocument, @@ -3660,8 +3707,8 @@ function* executeDocument( */ interface CanonicalInvocation { readonly execution: DocumentExecution; - readonly evaluateGeneratedXmdRoot: BoundRootEvaluator; - readonly approvalOwner: AppendApprovalOwner; + readonly evaluateGeneratedXmdRoot: HostExecution["evaluateGeneratedXmdRoot"]; + readonly approvals: ExecutionApprovals; /** This execution's own computed root data, for the trusted handle to read. */ readonly computed: ComputedBindings; /** @@ -4059,7 +4106,7 @@ function* runInvocation( return { evaluateGeneratedXmdRoot: invoked.evaluateGeneratedXmdRoot, - approvalOwner: invoked.approvalOwner, + approvals: invoked.approvals, computed: invoked.computed, stop: stopInvocation, // Carried through unchanged. The completion this handle publishes has @@ -4803,35 +4850,19 @@ export function* executeInstalled( installations: readonly ExecutionInstallation[], initialization?: ExecutionInitialization, ): Operation { - const { execution } = yield* executeInstalledBound(options, installations, initialization); - return execution; -} - -export function* executeInstalledWithApprovals( - options: ExecuteOptions, - installations: readonly ExecutionInstallation[], - initialization?: ExecutionInitialization, -): Operation<{ execution: HostExecution; approvals: AppendApprovals }> { - const { execution, approvals } = yield* executeInstalledBound( + const { execution } = yield* executeInstalledWithApprovals( options, installations, initialization, ); - return { execution, approvals }; -} - -export interface BoundExecution { - readonly execution: HostExecution; - readonly evaluate: BoundRootEvaluator; - readonly approvals: AppendApprovals; - registerGrant(grant: AppendGrant): Operation; + return execution; } -export function* executeInstalledBound( +export function* executeInstalledWithApprovals( options: ExecuteOptions, installations: readonly ExecutionInstallation[], initialization?: ExecutionInitialization, -): Operation { +): Operation<{ execution: HostExecution; approvals: ExecutionApprovals }> { const invoked = yield* runInvocation( options, [...installations], @@ -4863,9 +4894,7 @@ export function* executeInstalledBound( }, stop: invoked.stop, }, - evaluate: invoked.evaluateGeneratedXmdRoot, - approvals: invoked.approvalOwner.approvals, - registerGrant: invoked.approvalOwner.registerGrant, + approvals: invoked.approvals, }; } diff --git a/packages/core/src/expand.ts b/packages/core/src/expand.ts index 18804e4ee..c3b79cce5 100644 --- a/packages/core/src/expand.ts +++ b/packages/core/src/expand.ts @@ -348,7 +348,7 @@ export interface OutputFrame { readonly active: boolean; readonly private: boolean; readonly marks: WeakMap; - readonly replyLiteralOffsets?: WeakMap; + readonly sourceLiteralOffsets?: WeakMap; readonly stringSelection?: Set; } @@ -390,7 +390,7 @@ function bodyOutput(segments: Segment[], path: string, inherited?: OutputFrame): active: false, private: false, marks: inherited?.marks ?? new WeakMap(), - replyLiteralOffsets: inherited?.replyLiteralOffsets, + sourceLiteralOffsets: inherited?.sourceLiteralOffsets, }; } @@ -1256,7 +1256,7 @@ function* expandListSegments( type: "text", content: final, }; - const literals = outputFrame?.replyLiteralOffsets; + const literals = outputFrame?.sourceLiteralOffsets; const literal = literals?.get(segment); if ( literal !== undefined && diff --git a/packages/core/src/generated-root-owner.ts b/packages/core/src/generated-root-owner.ts index ddf9818d6..238c40555 100644 --- a/packages/core/src/generated-root-owner.ts +++ b/packages/core/src/generated-root-owner.ts @@ -3,8 +3,8 @@ * * A generated root is evaluated *by* an execution rather than beside one. What * it needs to run at all — the captured documentation reference, the guarded - * route canonical `` is entered through, the Agent providers and - * launch coordinator a document installs, the journal this run writes — all + * route canonical `` is entered through, the runtime services + * a document installs, the journal this run writes — all * belong to one live execution and are reachable nowhere else. So the public * method is a mailbox: a caller puts a request on the queue this owner is * reading, and the work happens inside the document's own scope, where that @@ -54,11 +54,28 @@ import { durableRun, preserveJournalProvenance, retainEvents } from "@executable import type { DurableEvent, DurableStream } from "@executablemd/durable-streams"; import type { - AcceptedRootReply, + GeneratedRootProvenance, GeneratedXmdRequest, GeneratedXmdRootResult, } from "./generated-xmd.ts"; +import { approvedGeneratedSource } from "./approved-generated-source.ts"; +import type { ApprovedElicitAnswer, ElicitChoiceSelection } from "./approved-generated-source.ts"; +import type { AppendApprovalOwner } from "./secrets/append-approval.ts"; +import type { ApprovedMatch } from "./secrets/secret-placement.ts"; + +/** The exact source and ranges approved for one evaluation by its host. */ +export interface GeneratedSourceApproval { + readonly source: string; + readonly matches: readonly ApprovedMatch[]; +} + +/** The evaluation result and its acknowledged copies from authored choices. */ +export interface ApprovedGeneratedXmdEvaluation { + readonly result: Result; + readonly answers: readonly ApprovedElicitAnswer[]; +} + /** Why this execution could not take the root evaluation it was asked for. */ export class HostExecutionError extends Error { override name = "HostExecutionError"; @@ -67,7 +84,7 @@ export class HostExecutionError extends Error { /** One execution's bound root evaluator, as the owner and the handle hold it. */ export type BoundRootEvaluator = ( request: GeneratedXmdRequest, - accepted?: AcceptedRootReply, + provenance?: GeneratedRootProvenance, ) => Operation>; /** What canonical execution hands its owner once both exist. */ @@ -83,6 +100,7 @@ export interface GeneratedRootInputs { readonly journal: DurableStream; /** The evaluator bound to this execution's captured authority. */ readonly evaluator: BoundRootEvaluator; + readonly approvals: AppendApprovalOwner; } /** The live owner of one execution's explicit root evaluations. */ @@ -93,7 +111,11 @@ export interface GeneratedRootOwner { * It closes over the queue and the owner's state, and over nothing a caller * could read: no evaluator, no journal, no route and no reference. */ - readonly evaluate: BoundRootEvaluator; + evaluate( + request: GeneratedXmdRequest, + approval?: GeneratedSourceApproval, + ): Operation; + selectElicitation(selection: ElicitChoiceSelection): void; /** Hand over the inputs, once, from inside the execution that holds them. */ supply(inputs: GeneratedRootInputs): void; /** @@ -142,7 +164,7 @@ export interface GeneratedRootOwner { /** What one caller asked this execution to evaluate. */ interface RootJob { readonly request: GeneratedXmdRequest; - readonly accepted?: AcceptedRootReply; + readonly provenance?: EvaluationProvenance; readonly answer: Resolvers; readonly cancelled: Resolvers; readonly joined: Resolvers; @@ -156,7 +178,9 @@ interface RootJob { * *run* keeps the identity and classification it already has, so it is carried * here unchanged and raised again in the caller's frame rather than described. */ -type Settled = { readonly value: Result } | { readonly raised: unknown }; +type Settled = { readonly value: ApprovedGeneratedXmdEvaluation } | { readonly raised: unknown }; + +type EvaluationProvenance = ReturnType; interface Resolvers { readonly operation: Operation; @@ -211,13 +235,20 @@ function sequenceOrder(event: DurableEvent): number | undefined { * backend's own object which coroutine it belongs to would be a read the index * is about to make again. */ -function evaluationJournal(journal: DurableStream, order: number): DurableStream { +function evaluationJournal( + journal: DurableStream, + order: number, + provenance: EvaluationProvenance | undefined, +): DurableStream { const view: DurableStream = { *readAll(): Operation { const events = retainEvents(yield* journal.readAll()); return events.filter((event) => sequenceOrder(event) === order); }, - append: (event: DurableEvent) => journal.append(event), + *append(event: DurableEvent): Operation { + yield* journal.append(event); + provenance?.acknowledge(event); + }, }; return preserveJournalProvenance(journal, view); } @@ -286,6 +317,7 @@ export function createGeneratedRootOwner(): GeneratedRootOwner { } }; let inputs: GeneratedRootInputs | undefined; + let activeProvenance: EvaluationProvenance | undefined; /** * Stop admitting evaluations and release everyone waiting on readiness. @@ -314,15 +346,15 @@ export function createGeneratedRootOwner(): GeneratedRootOwner { function evaluate( request: GeneratedXmdRequest, - accepted?: AcceptedRootReply, - ): Operation> { + approval?: GeneratedSourceApproval, + ): Operation { return scoped(function* () { // Before readiness, so two calls that arrive while the runner is still // starting are one admitted call and one refusal rather than two waiters. // Waiting for the runner is not queuing behind admitted work. const admitted = admit(); if (!admitted.ok) { - return admitted; + return { result: admitted, answers: [] }; } const answer = withResolvers(); const cancelled = withResolvers(); @@ -346,14 +378,33 @@ export function createGeneratedRootOwner(): GeneratedRootOwner { // then there is nothing left to do the joining. yield* race([joined.operation, closed.operation]); } finally { + activeProvenance = undefined; state.busy = false; } }); const started = yield* ready.operation; if (!started.ok) { - return started; + return { result: started, answers: [] }; } - jobs.add({ request, accepted, answer, cancelled, joined }); + const queuedRequest = approval === undefined ? request : { ...request }; + if (approval !== undefined && approval.source !== queuedRequest.source) { + return { + result: Err( + new HostExecutionError("the generated source differs from the approved source"), + ), + answers: [], + }; + } + const provenance = + approval === undefined + ? undefined + : approvedGeneratedSource({ + id: queuedRequest.id, + source: queuedRequest.source, + approved: approval.matches.map((match) => ({ ...match })), + }); + activeProvenance = provenance; + jobs.add({ request: queuedRequest, provenance, answer, cancelled, joined }); sent = true; // Raced against the execution closing, because a halted worker answers // nobody: the work it was doing has joined by the time this resolves, and @@ -363,7 +414,7 @@ export function createGeneratedRootOwner(): GeneratedRootOwner { answer.operation, (function* (): Operation { yield* closed.operation; - return { value: Err(new HostExecutionError(INTERRUPTED)) }; + return { value: { result: Err(new HostExecutionError(INTERRUPTED)), answers: [] } }; })(), ]); answered = true; @@ -376,6 +427,9 @@ export function createGeneratedRootOwner(): GeneratedRootOwner { return { evaluate, + selectElicitation(selection) { + activeProvenance?.select({ ...selection }); + }, completion: () => fatal, supply(supplied: GeneratedRootInputs): void { inputs = supplied; @@ -538,16 +592,20 @@ function sequence( inputs: GeneratedRootInputs, job: RootJob, order: number, -): Operation> { +): Operation { return scoped(function* () { const settled: { outcome?: Result } = {}; const coroutineId = sequenceName(order); - job.accepted?.grant.bind(coroutineId); + const { provenance } = job; + if (provenance !== undefined) { + provenance.bind(coroutineId); + yield* inputs.approvals.registerGrant(provenance); + } yield* durableRun( function* (): Operation { - settled.outcome = yield* inputs.evaluator(job.request, job.accepted); + settled.outcome = yield* inputs.evaluator(job.request, provenance); }, - { stream: evaluationJournal(inputs.journal, order), coroutineId }, + { stream: evaluationJournal(inputs.journal, order, provenance), coroutineId }, ); const outcome = settled.outcome; if (outcome === undefined) { @@ -555,6 +613,6 @@ function sequence( `the generated root on sequence "${coroutineId}" recorded no outcome`, ); } - return outcome; + return { result: outcome, answers: provenance?.answers() ?? [] }; }); } diff --git a/packages/core/src/generated-xmd.ts b/packages/core/src/generated-xmd.ts index e832ec7c7..b4286d4c4 100644 --- a/packages/core/src/generated-xmd.ts +++ b/packages/core/src/generated-xmd.ts @@ -139,7 +139,7 @@ import { markGeneratedRequestRefusal } from "./generated-request-refusal.ts"; import { GeneratedDataExpressions, validateDataExpression } from "./generated-expressions.ts"; import { capturedBinding } from "./invocation-rules.ts"; import { renderSegment, renderSegments } from "./render.ts"; -import type { ApprovedMatch, evaluationGrant } from "./secrets/reply-grant.ts"; +import type { ApprovedMatch } from "./secrets/secret-placement.ts"; import type { SecretDetection } from "./secrets/policy.ts"; import type { SourceRange } from "./document-targets.ts"; import { scanSegments } from "./scanner.ts"; @@ -738,9 +738,9 @@ export interface GeneratedRootBinding { readonly live: () => boolean; } -export interface AcceptedRootReply { - readonly approved: readonly ApprovedMatch[]; - readonly grant: ReturnType; +export interface GeneratedRootProvenance { + readonly matches: readonly ApprovedMatch[]; + readonly schemas: Map; } /** @@ -2476,7 +2476,7 @@ function expand( active: false, private: false, marks: new WeakMap(), - replyLiteralOffsets: literalOffsets, + sourceLiteralOffsets: literalOffsets, }, ); return renderSegments(owner ?? []); @@ -2743,21 +2743,18 @@ function safeDiagnostic(error: unknown): string { function* evaluateRoot( request: GeneratedXmdRequest, binding: GeneratedRootBinding, - accepted?: AcceptedRootReply, + provenance?: GeneratedRootProvenance, ): Operation> { // Allocated out here, so a failure partway leaves this frame holding exactly // what the root rendered before it. The flag is read from the source core // admitted rather than from the caller's copy, and it is the same reading // `expand` selects regions with. const owner: Segment[] = []; - const literalOffsets = accepted === undefined ? undefined : new WeakMap(); - if (accepted !== undefined) { - yield* ensure(binding.detection.allowReplyCopies(accepted.grant)); - } + const literalOffsets = provenance === undefined ? undefined : new WeakMap(); const check = (output: string) => - binding.detection.checkReplyText( + binding.detection.clearText( output, - outputCopies(owner, literalOffsets, accepted?.approved ?? []), + outputCopies(owner, literalOffsets, provenance?.matches ?? []), ); let hasOutput = false; try { @@ -2788,7 +2785,7 @@ function* evaluateRoot( { owner, literalOffsets, - schemas: accepted?.grant.schemas, + schemas: provenance?.schemas, declared: (value) => { hasOutput = value; }, @@ -2872,7 +2869,7 @@ export function bindGeneratedRootEvaluator( binding: GeneratedRootBinding, ): ( request: GeneratedXmdRequest, - accepted?: AcceptedRootReply, + provenance?: GeneratedRootProvenance, ) => Operation> { - return (request, accepted) => evaluateRoot(request, binding, accepted); + return (request, provenance) => evaluateRoot(request, binding, provenance); } diff --git a/packages/core/src/secrets/append-approval.ts b/packages/core/src/secrets/append-approval.ts index 543edc969..565a8f9ea 100644 --- a/packages/core/src/secrets/append-approval.ts +++ b/packages/core/src/secrets/append-approval.ts @@ -24,7 +24,6 @@ export interface AppendApprovals { export interface AppendGrant { claims(event: DurableEvent): boolean; admits(event: DurableEvent, serialized: string, spans: readonly SecretSpan[]): boolean; - published?(event: DurableEvent): void; } export interface AppendApprovalOwner { diff --git a/packages/core/src/secrets/policy.ts b/packages/core/src/secrets/policy.ts index bd7dafb1d..b8c5abdb4 100644 --- a/packages/core/src/secrets/policy.ts +++ b/packages/core/src/secrets/policy.ts @@ -405,8 +405,9 @@ export function* useSecretDetection( return { journal: stream, disclose: projectedDisclosure(discloseFreely), - checkReplyText: replyTextCheck(undefined, inputs), - allowReplyCopies: () => () => {}, + clearText: textClearance(undefined, inputs), + scan: () => scanWith(undefined), + locateText: (text) => locateTextMatches(undefined, inputs, text), }; } @@ -416,13 +417,9 @@ export function* useSecretDetection( return { journal: guardWithSecretDetection(stream, scanner, grants), disclose: projectedDisclosure(discloseThrough(scanner)), - checkReplyText: replyTextCheck(scanner, inputs), - allowReplyCopies(grant) { - grants.add(grant); - return () => { - grants.delete(grant); - }; - }, + clearText: textClearance(scanner, inputs), + scan: (text) => scanWith(scanner, text), + locateText: (text) => locateTextMatches(scanner, inputs, text), }; } @@ -438,24 +435,17 @@ export function* useSecretDetection( export interface SecretDetection { readonly journal: DurableStream; readonly disclose: SecretDisclosure; - readonly checkReplyText: ReplyTextCheck; - allowReplyCopies(grant: AppendGrant): () => void; + readonly clearText: TextClearance; + scan(text: string): Operation; + locateText(text: string): Operation; } -export type ReplyTextCheck = (text: string, copies: readonly ApprovedMatch[]) => Operation; +export type TextClearance = (text: string, copies: readonly ApprovedMatch[]) => Operation; -export function* captureReplyTextCheck(): Operation { - const detection = yield* currentDetection(); - return replyTextCheck( - detection instanceof EnabledDetection ? detection.scanner : undefined, - detection.inputs, - ); -} - -function replyTextCheck( +function textClearance( scanner: SecretScanner | undefined, inputs: InputValues | undefined, -): ReplyTextCheck { +): TextClearance { return function* (text, copies) { if (inputs !== undefined) { const projected = inputs.display(text); @@ -557,15 +547,7 @@ function guardWithSecretDetection( throw new SecretDetectedError(findings); } }); - return preserveJournalProvenance(stream, { - readAll: () => guarded.readAll(), - *append(event) { - yield* guarded.append(event); - for (const grant of grants) { - grant.published?.(event); - } - }, - }); + return preserveJournalProvenance(stream, guarded); /** * Whether one live grant accounts for every finding in this event. @@ -587,27 +569,21 @@ function guardWithSecretDetection( } } -/** - * Where this execution's scanner finds credentials in one completed reply, in - * the reply's own coordinates — or nothing when it cannot say exactly. - * - * Scanned the way the journal will hold it, as a JSON string, so a span is a - * span of what the gate refused. A reply that holds a protected input, a - * scanner this module did not build, a range that falls inside an escape, and - * a scanner that fails all answer nothing: the reply stays withheld and is - * never offered for approval. - */ -export function* locateReplySecrets(text: string): Operation { - let detection: ExecutionDetection; - try { - detection = yield* currentDetection(); - } catch { - return undefined; - } - if (!(detection instanceof EnabledDetection)) { +function* scanWith( + scanner: SecretScanner | undefined, + text = "", +): Operation { + return scanner === undefined ? [] : yield* scanner.scan(text); +} + +function* locateTextMatches( + scanner: SecretScanner | undefined, + inputs: InputValues | undefined, + text: string, +): Operation { + if (scanner === undefined) { return undefined; } - const inputs = detection.inputs; if (inputs !== undefined) { const shown = inputs.display(text); if (inputs.contains(text) || !shown.ok || shown.value !== text) { @@ -616,7 +592,7 @@ export function* locateReplySecrets(text: string): Operation { ); } -function* openNote(stream: InMemoryStream, body: (approvals: AppendApprovals) => Operation) { - const bridge = withResolvers(); +function* openNote( + stream: InMemoryStream, + body: (approvals: ExecutionApprovals) => Operation, + extra: readonly ExecutionInstallation[] = [], +) { + const bridge = withResolvers(); const installation: ExecutionInstallation = { components: [ { @@ -57,7 +69,7 @@ function* openNote(stream: InMemoryStream, body: (approvals: AppendApprovals) => }; const { execution, approvals } = yield* executeInstalledWithApprovals( { ...retainedSource("host-note.md", "\n"), stream }, - [installation], + [installation, ...extra], ); expect(execution).not.toHaveProperty("approvals"); bridge.resolve(approvals); @@ -149,3 +161,83 @@ describe("a trusted host's append approval", () => { expect(notes(stream)).toEqual([{ status: "ok", value: { note: text } }]); }); }); + +describe("a trusted host's generated-source approval", () => { + it("clears selected Output and returns acknowledged Elicit value and source ranges", function* () { + yield* useMarkerDetector(); + const stream = new InMemoryStream(); + const choice = `${marker} and ${marker}`; + const schema = { type: "object", properties: { choice: { type: "string", enum: [choice] } } }; + const source = + `Choose one\n\n` + + `\n${marker}\n\n`; + const matches = Array.from(source.matchAll(/synthetic-marker/g), ({ index }) => ({ + ...match, + bytes: marker, + start: index, + end: index + marker.length, + })); + const request = { id: "note", source, allow: ["write"] } as const; + let selectingChoice: ExecutionApprovals | undefined; + yield* Elicitation.around({ + *elicit([request]) { + selectingChoice?.selectElicitation({ + ...(yield* durablePosition()), + name: elicitationEffectName((yield* getExpansion()).position), + fingerprint: questionFingerprint(request), + field: "choice", + option: 0, + }); + return { choice }; + }, + }); + const completion = yield* openNote( + stream, + function* (approvals) { + selectingChoice = approvals; + const changed = yield* approvals.evaluateGeneratedXmdRoot( + { ...request, source: request.source + "\n" }, + { source, matches }, + ); + expect(changed.result.ok).toBe(false); + expect(changed.answers).toEqual([]); + + const ran = yield* approvals.evaluateGeneratedXmdRoot(request, { source, matches }); + if (!ran.result.ok) { + throw ran.result.error; + } + expect(ran.result.value.output).toContain(marker); + const events = stream.snapshot(); + const acknowledged = events.find( + (event) => event.type === "yield" && event.description.type === "elicit", + ); + const index = events + .filter( + (event) => event.type === "yield" && event.coroutineId === acknowledged?.coroutineId, + ) + .indexOf(acknowledged!); + expect(index).toBeGreaterThanOrEqual(0); + expect(ran.answers).toEqual([ + { + coroutineId: acknowledged?.coroutineId, + index, + value: { choice }, + copies: matches.slice(0, 2).map(({ start, end, ...copy }, index) => ({ + field: "choice", + source: { start, end }, + match: { + ...copy, + start: index * (marker.length + 5), + end: index * (marker.length + 5) + marker.length, + }, + })), + }, + ]); + }, + [selecting({ Elicit: ["paired"] })], + ); + if (!completion.ok) { + throw completion.error; + } + }); +}); diff --git a/specs/executable-mdx-spec.md b/specs/executable-mdx-spec.md index a0b4943b5..b7e4cc2cd 100644 --- a/specs/executable-mdx-spec.md +++ b/specs/executable-mdx-spec.md @@ -11259,10 +11259,11 @@ contract. The REPL can ask about a located finding in one completed Sidekick reply after the canonical withheld Prompt is acknowledged. Its trusted foreground -decision reaches Core through the still-live continuation of that turn. Core -publishes a distinct acceptance immediately after that Prompt in the same -root sequence, carrying the exact original reply and an audit of approved -rule, message and ranges. The original Prompt and its receipt stand. The +decision reaches the Agent conversation through the still-live continuation of +that turn. The conversation publishes a distinct acceptance immediately after +that Prompt in the same root sequence, carrying the exact original reply and an +audit of approved rule, message and ranges. The original Prompt and its receipt +stand. The acceptance uses no new turn ordinal. Replay restores the pair without recovering a live approval or contacting a provider. @@ -11274,8 +11275,8 @@ Core clears the actual selected Output, including selected partial Output, before the Sidekick response writer or ACP receives it. An unchanged literal in selected rendering can carry its approved range. A normalized Elicit enum choice can carry its authored range into the acknowledged answer when the -foreground form selected that choice in the same field. The next feedback -turn verifies the exact composed input before retaining an intent or reaching +foreground form selected that choice in the same field. The Agent conversation +checks the exact composed input before retaining a feedback intent or reaching the provider. Appended context preserves approval for exact ranges in the unchanged original feedback prefix. The scanner applies ordinary detection to findings in appended context, across the join, and in the next reply. From b7189532197bae876bbfa578fb136689176383cb Mon Sep 17 00:00:00 2001 From: Taras Mankovski Date: Sun, 15 Nov 2026 14:28:58 -0500 Subject: [PATCH 3/6] Extract the Agent package from Core Move packages/core/src/agent into the new publishable @executablemd/agent package with ./api and ./host entries, and remove every Agent export from Core's root, API and host. Agent production code reaches Core only through its public entries; Core's host gains the narrow failure, source-owner and approved-copy placement helpers that requires. Registrations, identity components and documentation keep the @executablemd/core origin and the synthetic conversation root is unchanged. Migrate CLI, ACP, Workflow, Test Agent, examples and tests to the new entries, move the Agent suites and PA4 into the package, add the package boundary tests, and update manifests, locks, packaging, the publish workflow, specs, architecture and the README map. Co-Authored-By: Claude Opus 5.5 --- .github/workflows/publish-packages.yml | 17 +- README.md | 5 + architecture.md | 12 ++ bun.lock | 19 ++ deno.lock | 16 +- .../components/Delivery/Inspect.ts | 2 +- .../components/Delivery/Turn.ts | 7 +- .../components/Phase/Session.ts | 5 +- .../tests/acp-overlap/local-workers.ts | 2 +- .../tests/components/Fixture/Session.ts | 5 +- .../production-components/NativeGuide.ts | 3 +- examples/agent-certification/observe.ts | 5 +- examples/agent-certification/report.ts | 2 +- examples/agent-certification/stage-runner.ts | 3 +- examples/agent-usage/calibrate.ts | 2 +- examples/agent-usage/evidence.ts | 6 +- examples/agent-usage/report.ts | 2 +- examples/repl-bench/lib/scripted-sidekick.ts | 4 +- examples/repl-bench/lib/wheel-permission.ts | 2 +- examples/repl-plugins/counter.ts | 3 +- knip.json | 4 + package.json | 1 + packages/acp/package.json | 1 + packages/acp/src/checkpoint.ts | 2 +- packages/acp/src/events.ts | 2 +- packages/acp/src/native-launch.ts | 2 +- packages/acp/src/permission-bridge.ts | 5 +- packages/acp/src/provider.ts | 10 +- packages/acp/src/session-configuration.ts | 2 +- packages/acp/src/session-route.ts | 2 +- packages/acp/src/usage.ts | 2 +- packages/acp/src/xmd-response.ts | 2 +- packages/acp/tests/acceptance.test.ts | 5 +- .../acp/tests/acpx-materialization.test.ts | 4 +- .../acp/tests/agent-certification.test.ts | 11 +- packages/acp/tests/claude-reconnect.test.ts | 12 +- packages/acp/tests/host-conversation.test.ts | 16 +- packages/acp/tests/loaded-copy.test.ts | 76 ++++++-- packages/acp/tests/native-launch.test.ts | 12 +- packages/acp/tests/permission-bridge.test.ts | 4 +- packages/acp/tests/provider.test.ts | 11 +- packages/acp/tests/released-runtime.test.ts | 14 +- packages/acp/tests/session-route.test.ts | 2 +- packages/agent/api.ts | 178 ++++++++++++++++++ packages/agent/deno.json | 12 ++ packages/agent/host.ts | 136 +++++++++++++ packages/agent/package.json | 18 ++ .../src/agent => agent/src}/agent-api.ts | 2 +- .../src/agent => agent/src}/checkpoint.ts | 0 .../src/agent => agent/src}/components.md | 12 +- .../src/agent => agent/src}/components.ts | 45 +++-- .../src}/configuration-record.ts | 2 +- .../src}/conversation-provider.ts | 0 .../src/agent => agent/src}/conversation.ts | 52 +++-- .../{core/src/agent => agent/src}/errors.ts | 0 .../src}/function-components.ts | 43 +++-- .../{core/src/agent => agent/src}/internal.ts | 2 +- .../{core/src/agent => agent/src}/journal.ts | 23 ++- .../agent => agent/src}/launch-coordinator.ts | 0 .../src/agent => agent/src}/launch-install.ts | 0 .../src/agent => agent/src}/launch-journal.ts | 4 +- .../src/agent => agent/src}/launch-owner.ts | 2 +- .../src/agent => agent/src}/launch-request.ts | 0 .../{core/src/agent => agent/src}/launch.ts | 0 packages/agent/src/origin.ts | 11 ++ .../src/agent => agent/src}/permission.ts | 0 .../src/agent => agent/src}/provider-api.ts | 0 .../src}/provider-configuration.ts | 4 +- .../src/agent => agent/src}/publication.ts | 0 .../agent => agent/src}/reply-acceptance.ts | 4 +- .../src/agent => agent/src}/reply-review.ts | 5 +- .../agent => agent/src}/session-request.ts | 0 .../src/agent => agent/src}/session-setup.ts | 0 .../src/agent => agent/src}/session-use.ts | 0 .../{core/src/agent => agent/src}/usage.ts | 2 +- .../{core => agent}/tests/agent-api.test.ts | 70 ++++++- .../tests/agent-components.test.ts | 22 +-- .../tests/agent-conversation.test.ts | 63 ++++--- .../tests/agent-function-components.test.ts | 41 ++-- .../tests/agent-session-launch.test.ts | 30 +-- .../tests/agent-session-setup.test.ts | 14 +- .../agent-session-use-loaded-copy.test.ts | 6 +- .../tests/agent-session-use.test.ts | 4 +- .../{core => agent}/tests/agent-stack.test.ts | 22 +-- .../{core => agent}/tests/agent-usage.test.ts | 51 +++-- packages/agent/tests/package-boundary.test.ts | 168 +++++++++++++++++ packages/agent/tests/package-graph.test.ts | 79 ++++++++ .../tests/root-provider.test.ts | 24 +-- packages/cli/package.json | 1 + packages/cli/src/agent-config.ts | 2 +- packages/cli/src/agent-options.ts | 2 +- packages/cli/src/agent-stack.ts | 9 +- packages/cli/src/cli.ts | 6 +- packages/cli/src/diagnostic-agent.ts | 2 +- packages/cli/src/headless/host.ts | 6 +- packages/cli/src/plan-component.ts | 2 +- packages/cli/src/plan-writer-profile.ts | 14 +- packages/cli/src/repl-profile.ts | 5 +- packages/cli/src/repl/agent.ts | 10 +- packages/cli/src/repl/application.ts | 2 +- packages/cli/src/repl/model.ts | 5 +- packages/cli/src/repl/program.ts | 3 +- packages/cli/src/repl/session.ts | 3 +- packages/cli/src/repl/sidekick/assembly.ts | 4 +- packages/cli/src/repl/sidekick/asset-image.ts | 2 +- packages/cli/src/repl/sidekick/feedback.ts | 2 +- packages/cli/src/repl/sidekick/model.ts | 8 +- packages/cli/src/repl/sidekick/owner.ts | 16 +- packages/cli/src/repl/sidekick/questions.ts | 2 +- .../cli/src/repl/sidekick/recovery-owner.ts | 2 +- .../cli/src/repl/sidekick/recovery-state.ts | 2 +- packages/cli/src/repl/sidekick/testing.ts | 2 +- packages/cli/src/repl/todo/service.ts | 4 +- packages/cli/src/repl/usage.ts | 2 +- packages/cli/src/syntax.ts | 8 +- packages/cli/src/testing-host.ts | 8 +- packages/cli/src/workflow-agent.ts | 11 +- .../cli/tests/adversarial-diagnosis.test.ts | 8 +- .../adversarial-session-continuity.test.ts | 16 +- .../cli/tests/agent-certification.test.ts | 3 +- packages/cli/tests/agent-config.test.ts | 2 +- packages/cli/tests/agent-options.test.ts | 2 +- .../tests/agent-session-coordinator.test.ts | 4 +- .../cli/tests/agent-usage-calibration.test.ts | 2 +- packages/cli/tests/fixtures/host-agent.ts | 3 +- .../tests/fixtures/repl/contributed-plugin.ts | 3 +- .../fixtures/repl/issue-883/recovery-phase.ts | 4 +- packages/cli/tests/fixtures/repl/reference.ts | 8 +- .../cli/tests/plan-command-document.test.ts | 8 +- packages/cli/tests/plan-component.test.ts | 9 +- packages/cli/tests/prompt-usage-hosts.test.ts | 8 +- .../cli/tests/repl-agent-execution.test.ts | 15 +- .../cli/tests/repl-agent-interface.test.ts | 11 +- packages/cli/tests/repl-execution.test.ts | 9 +- .../cli/tests/repl-headless-clients.test.ts | 2 +- packages/cli/tests/repl-headless.test.ts | 5 +- packages/cli/tests/repl-sidekick-acp.test.ts | 5 +- .../cli/tests/repl-sidekick-controls.test.ts | 5 +- .../cli/tests/repl-sidekick-dispatch.test.ts | 2 +- .../cli/tests/repl-sidekick-recovery.test.ts | 6 +- .../cli/tests/repl-sidekick-resume.test.ts | 7 +- packages/cli/tests/repl-todo-context.test.ts | 5 +- .../cli/tests/run-composition-deno.test.ts | 11 +- .../cli/tests/run-composition-nested.test.ts | 3 +- .../cli/tests/testing-execution-host.test.ts | 2 +- .../cli/tests/workflow-agent-sessions.test.ts | 8 +- packages/cli/tests/workflow-agent.test.ts | 2 +- .../cli/tests/workflow-suspension.test.ts | 13 +- packages/core/api.ts | 75 -------- packages/core/deno.json | 1 - packages/core/host.ts | 122 +++--------- packages/core/mod.ts | 122 ------------ packages/core/src/errors.ts | 19 ++ packages/core/src/secrets/policy.ts | 16 +- packages/core/src/secrets/secret-placement.ts | 31 +++ packages/core/src/source-owner.ts | 14 ++ packages/core/tests/all.test.ts | 6 +- packages/core/tests/plugin-api.test.ts | 61 +----- packages/core/tests/syntax-catalog.test.ts | 3 +- .../core/tests/try-catch-finally-harness.ts | 8 +- packages/test-agent/package.json | 1 + .../test-agent/src/child-configuration.ts | 9 +- packages/test-agent/src/components.ts | 13 +- .../test-agent/tests/command-lazy.test.ts | 3 +- packages/test-agent/tests/components.test.ts | 9 +- .../tests/cross-package-resolution.test.ts | 3 +- .../test-agent/tests/native-launch.test.ts | 5 +- packages/test-agent/tests/provider.test.ts | 2 +- .../tests/session-configuration.test.ts | 9 +- packages/test-agent/tests/smoke.test.ts | 8 +- .../testing/tests/agent-composition.test.ts | 8 +- packages/workflow/package.json | 1 + .../workflow/src/deno/agent-publication.ts | 2 +- .../workflow/src/deno/artifact/records.ts | 4 +- .../tests/workflow-agent-checkpoints.test.ts | 19 +- pnpm-lock.yaml | 36 ++++ scripts/build-npm.ts | 1 - scripts/lib/compile.ts | 2 +- scripts/runtime-test-exclusions.ts | 10 +- scripts/smoke-documentation.ts | 23 +++ scripts/smoke-prompt-usage.ts | 2 +- scripts/tests/cli-npm-bin.test.ts | 6 +- .../tests/jsr-consumer-documentation.test.ts | 44 +++-- scripts/tests/packaged-document.test.ts | 6 +- specs/acp-client-spec.md | 43 +++-- specs/executable-mdx-spec.md | 16 +- tsconfig.node.json | 3 + 187 files changed, 1569 insertions(+), 1008 deletions(-) create mode 100644 packages/agent/api.ts create mode 100644 packages/agent/deno.json create mode 100644 packages/agent/host.ts create mode 100644 packages/agent/package.json rename packages/{core/src/agent => agent/src}/agent-api.ts (99%) rename packages/{core/src/agent => agent/src}/checkpoint.ts (100%) rename packages/{core/src/agent => agent/src}/components.md (90%) rename packages/{core/src/agent => agent/src}/components.ts (93%) rename packages/{core/src/agent => agent/src}/configuration-record.ts (99%) rename packages/{core/src/agent => agent/src}/conversation-provider.ts (100%) rename packages/{core/src/agent => agent/src}/conversation.ts (97%) rename packages/{core/src/agent => agent/src}/errors.ts (100%) rename packages/{core/src/agent => agent/src}/function-components.ts (98%) rename packages/{core/src/agent => agent/src}/internal.ts (98%) rename packages/{core/src/agent => agent/src}/journal.ts (98%) rename packages/{core/src/agent => agent/src}/launch-coordinator.ts (100%) rename packages/{core/src/agent => agent/src}/launch-install.ts (100%) rename packages/{core/src/agent => agent/src}/launch-journal.ts (99%) rename packages/{core/src/agent => agent/src}/launch-owner.ts (99%) rename packages/{core/src/agent => agent/src}/launch-request.ts (100%) rename packages/{core/src/agent => agent/src}/launch.ts (100%) create mode 100644 packages/agent/src/origin.ts rename packages/{core/src/agent => agent/src}/permission.ts (100%) rename packages/{core/src/agent => agent/src}/provider-api.ts (100%) rename packages/{core/src/agent => agent/src}/provider-configuration.ts (98%) rename packages/{core/src/agent => agent/src}/publication.ts (100%) rename packages/{core/src/agent => agent/src}/reply-acceptance.ts (98%) rename packages/{core/src/agent => agent/src}/reply-review.ts (97%) rename packages/{core/src/agent => agent/src}/session-request.ts (100%) rename packages/{core/src/agent => agent/src}/session-setup.ts (100%) rename packages/{core/src/agent => agent/src}/session-use.ts (100%) rename packages/{core/src/agent => agent/src}/usage.ts (99%) rename packages/{core => agent}/tests/agent-api.test.ts (73%) rename packages/{core => agent}/tests/agent-components.test.ts (97%) rename packages/{core => agent}/tests/agent-conversation.test.ts (98%) rename packages/{core => agent}/tests/agent-function-components.test.ts (98%) rename packages/{core => agent}/tests/agent-session-launch.test.ts (99%) rename packages/{core => agent}/tests/agent-session-setup.test.ts (98%) rename packages/{core => agent}/tests/agent-session-use-loaded-copy.test.ts (97%) rename packages/{core => agent}/tests/agent-session-use.test.ts (98%) rename packages/{core => agent}/tests/agent-stack.test.ts (95%) rename packages/{core => agent}/tests/agent-usage.test.ts (94%) create mode 100644 packages/agent/tests/package-boundary.test.ts create mode 100644 packages/agent/tests/package-graph.test.ts rename packages/{core => agent}/tests/root-provider.test.ts (96%) diff --git a/.github/workflows/publish-packages.yml b/.github/workflows/publish-packages.yml index 2818c2e64..1efc60ac2 100644 --- a/.github/workflows/publish-packages.yml +++ b/.github/workflows/publish-packages.yml @@ -30,7 +30,7 @@ jobs: - name: Validate the manifests declare this version run: | VERSION="${{ steps.resolve.outputs.value }}" - for f in packages/durable-streams/deno.json packages/runtime/deno.json packages/core/deno.json packages/acp/deno.json packages/workflow/deno.json packages/git/deno.json packages/testing/deno.json packages/test-agent/deno.json packages/web/deno.json packages/cli/deno.json; do + for f in packages/durable-streams/deno.json packages/runtime/deno.json packages/core/deno.json packages/agent/deno.json packages/acp/deno.json packages/workflow/deno.json packages/git/deno.json packages/testing/deno.json packages/test-agent/deno.json packages/web/deno.json packages/cli/deno.json; do declared="$(jq -r .version "$f")" if [ "$declared" != "$VERSION" ]; then echo "::error::$f declares $declared, not $VERSION — the tag does not match the manifests" @@ -82,15 +82,22 @@ jobs: package: packages/core version: ${{ needs.version.outputs.value }} + agent: + needs: [version, core, durable-streams, runtime] + uses: ./.github/workflows/publish-one.yml + with: + package: packages/agent + version: ${{ needs.version.outputs.value }} + acp: - needs: [version, core, runtime] + needs: [version, agent, core, runtime] uses: ./.github/workflows/publish-one.yml with: package: packages/acp version: ${{ needs.version.outputs.value }} workflow: - needs: [version, core, durable-streams, runtime] + needs: [version, agent, core, durable-streams, runtime] uses: ./.github/workflows/publish-one.yml with: package: packages/workflow @@ -111,7 +118,7 @@ jobs: version: ${{ needs.version.outputs.value }} test-agent: - needs: [version, acp, core, durable-streams, runtime, testing] + needs: [version, acp, agent, core, durable-streams, runtime, testing] uses: ./.github/workflows/publish-one.yml with: package: packages/test-agent @@ -125,7 +132,7 @@ jobs: version: ${{ needs.version.outputs.value }} cli: - needs: [version, acp, core, durable-streams, git, runtime, test-agent, testing, web, workflow] + needs: [version, acp, agent, core, durable-streams, git, runtime, test-agent, testing, web, workflow] uses: ./.github/workflows/publish-one.yml with: package: packages/cli diff --git a/README.md b/README.md index 2d13292de..d6d8f1ec3 100644 --- a/README.md +++ b/README.md @@ -41,6 +41,11 @@ Locate the package that owns the behavior you are about to change: - `packages/core/` — the engine: the boundary scanner, component expansion, `exec` and `eval`, modifiers, and the `execute()` entry point. +- `packages/agent/` — the Agent components (``, ``, + ``, `` and the permission regions), the `Agent` Api, Prompt + journaling and held conversations. A Plugin imports `Agent` from + `@executablemd/agent/api`; a host installs the components from + `@executablemd/agent/host`. - `packages/cli/` — the `xmd` command. `src/cli.ts` is runtime-neutral; `src/{deno,node,bun,compiled}.ts` install the host adapters each runtime needs. - `packages/runtime/` — the contextual host APIs — process, filesystem, env, diff --git a/architecture.md b/architecture.md index ce9eae1b8..beeeb340f 100644 --- a/architecture.md +++ b/architecture.md @@ -82,6 +82,18 @@ Providers answer those operations. Runtime entrypoints install the appropriate a `@executablemd/git` owns repository composition, Git operations, Git-host behavior, issues, and pull requests. It extends Workflow through Workflow’s published boundaries; Workflow imports no Git feature. +`@executablemd/agent` owns the Agent vocabulary over Core: the `Agent` Api, +the Agent, Session and Prompt components, Prompt journaling, provider +installation and held conversations. It depends on Core, durable-streams and +runtime, and reaches Core only through Core's published entries; Core imports no +Agent package and registers no Agent component by itself. Components and +Plugins compose agent work through `@executablemd/agent/api`; a host installs +the vocabulary, a provider and a held conversation through +`@executablemd/agent/host`, and its generic `Plugin` and execution imports stay +Core's. The components keep the origin `@executablemd/core` they had when Core +shipped them, so authored documents and retained journals read the same. ACP, +Workflow, Test Agent and the CLI import Agent's entries directly. + An Agent provider supplies conversation behavior. The Agent proposes source; canonical generated evaluation admits and performs it. Provider conversation continuity has its own contract in the [ACP client specification](specs/acp-client-spec.md). Ordinary Agent Session placement is inert: a placed session contacts nothing diff --git a/bun.lock b/bun.lock index c8f67edbf..a9ecc5c93 100644 --- a/bun.lock +++ b/bun.lock @@ -32,6 +32,7 @@ "devDependencies": { "@durable-streams/server": "^0.3.8", "@executablemd/acp": "workspace:*", + "@executablemd/agent": "workspace:*", "@executablemd/cli": "workspace:*", "@executablemd/core": "workspace:*", "@executablemd/durable-streams": "workspace:*", @@ -54,12 +55,25 @@ "name": "@executablemd/acp", "version": "0.14.1", "dependencies": { + "@executablemd/agent": "workspace:*", "@executablemd/core": "workspace:*", "@executablemd/runtime": "workspace:*", "acpx": "0.12.0", "effection": "4.1.0", }, }, + "packages/agent": { + "name": "@executablemd/agent", + "version": "0.14.1", + "dependencies": { + "@effectionx/context-api": "0.6.0", + "@executablemd/core": "workspace:*", + "@executablemd/durable-streams": "workspace:*", + "@executablemd/runtime": "workspace:*", + "effection": "4.1.0", + "zod": "^4.3.6", + }, + }, "packages/cli": { "name": "@executablemd/cli", "version": "0.14.1", @@ -69,6 +83,7 @@ "dependencies": { "@effectionx/stream-helpers": "0.8.3", "@executablemd/acp": "workspace:*", + "@executablemd/agent": "workspace:*", "@executablemd/core": "workspace:*", "@executablemd/durable-streams": "workspace:*", "@executablemd/git": "workspace:*", @@ -157,6 +172,7 @@ "@effectionx/scope-eval": "0.1.3", "@effectionx/stream-helpers": "0.8.3", "@executablemd/acp": "workspace:*", + "@executablemd/agent": "workspace:*", "@executablemd/core": "workspace:*", "@executablemd/durable-streams": "workspace:*", "@executablemd/runtime": "workspace:*", @@ -224,6 +240,7 @@ "@effectionx/context-api": "0.6.0", "@effectionx/fs": "0.3.0", "@effectionx/process": "0.8.1", + "@executablemd/agent": "workspace:*", "@executablemd/core": "workspace:*", "@executablemd/durable-streams": "workspace:*", "@executablemd/runtime": "workspace:*", @@ -328,6 +345,8 @@ "@executablemd/acp": ["@executablemd/acp@workspace:packages/acp"], + "@executablemd/agent": ["@executablemd/agent@workspace:packages/agent"], + "@executablemd/cli": ["@executablemd/cli@workspace:packages/cli"], "@executablemd/core": ["@executablemd/core@workspace:packages/core"], diff --git a/deno.lock b/deno.lock index 6d5d22e13..776d87c2b 100644 --- a/deno.lock +++ b/deno.lock @@ -4890,6 +4890,19 @@ ] } }, + "packages/agent": { + "dependencies": [ + "npm:@effectionx/context-api@0.6.0", + "npm:zod@^4.3.6" + ], + "packageJson": { + "dependencies": [ + "npm:@effectionx/context-api@0.6.0", + "npm:effection@4.1.0", + "npm:zod@^4.3.6" + ] + } + }, "packages/cli": { "dependencies": [ "npm:@agentclientprotocol/sdk@1.3.0", @@ -4929,8 +4942,7 @@ "npm:remark@15", "npm:remend@^1.2.2", "npm:unist-util-select@5", - "npm:yq.rs@0.1.4", - "npm:zod@^4.3.6" + "npm:yq.rs@0.1.4" ], "packageJson": { "dependencies": [ diff --git a/examples/adversarial-implementation/components/Delivery/Inspect.ts b/examples/adversarial-implementation/components/Delivery/Inspect.ts index 8e89ac97d..3521f0b0f 100644 --- a/examples/adversarial-implementation/components/Delivery/Inspect.ts +++ b/examples/adversarial-implementation/components/Delivery/Inspect.ts @@ -1,4 +1,4 @@ -import { Agent } from "@executablemd/core/api"; +import { Agent } from "@executablemd/agent/api"; import type { Operation } from "effection"; import { z } from "zod"; import { describeFailure, isFilesFailure } from "./failure.ts"; diff --git a/examples/adversarial-implementation/components/Delivery/Turn.ts b/examples/adversarial-implementation/components/Delivery/Turn.ts index 4e3300a98..26c576db3 100644 --- a/examples/adversarial-implementation/components/Delivery/Turn.ts +++ b/examples/adversarial-implementation/components/Delivery/Turn.ts @@ -1,6 +1,7 @@ -import { AgentPromptError } from "@executablemd/core"; -import { Agent, Component } from "@executablemd/core/api"; -import type { AgentPromptEvent } from "@executablemd/core/api"; +import { AgentPromptError } from "@executablemd/agent/api"; +import { Component } from "@executablemd/core/api"; +import { Agent } from "@executablemd/agent/api"; +import type { AgentPromptEvent } from "@executablemd/agent/api"; import type { Operation, Stream } from "effection"; import { z } from "zod"; import { diff --git a/examples/adversarial-implementation/components/Phase/Session.ts b/examples/adversarial-implementation/components/Phase/Session.ts index c10c6f5c4..be7b48bdc 100644 --- a/examples/adversarial-implementation/components/Phase/Session.ts +++ b/examples/adversarial-implementation/components/Phase/Session.ts @@ -1,5 +1,6 @@ -import { Agent, Component } from "@executablemd/core/api"; -import type { AgentPromptEvent } from "@executablemd/core/api"; +import { Component } from "@executablemd/core/api"; +import { Agent } from "@executablemd/agent/api"; +import type { AgentPromptEvent } from "@executablemd/agent/api"; import { API, cwd, parseFilesFailure } from "@executablemd/runtime"; import { ensure, type Stream } from "effection"; import { z } from "zod"; diff --git a/examples/adversarial-implementation/tests/acp-overlap/local-workers.ts b/examples/adversarial-implementation/tests/acp-overlap/local-workers.ts index 2b826cf95..50e8324c3 100644 --- a/examples/adversarial-implementation/tests/acp-overlap/local-workers.ts +++ b/examples/adversarial-implementation/tests/acp-overlap/local-workers.ts @@ -1,5 +1,5 @@ import { createAcpRuntime, createAcpxProvider, createAcpxSessionStore } from "@executablemd/acp"; -import { AgentProviders, registerAgentProvider } from "@executablemd/core"; +import { AgentProviders, registerAgentProvider } from "@executablemd/agent/api"; import { Component, Plugin } from "@executablemd/core/api"; import { API, command, env, readTextFile } from "@executablemd/runtime"; import { useTestAgentController } from "@executablemd/test-agent"; diff --git a/examples/adversarial-implementation/tests/components/Fixture/Session.ts b/examples/adversarial-implementation/tests/components/Fixture/Session.ts index effdf5230..9eb535d9b 100644 --- a/examples/adversarial-implementation/tests/components/Fixture/Session.ts +++ b/examples/adversarial-implementation/tests/components/Fixture/Session.ts @@ -1,5 +1,6 @@ -import { Agent, Component } from "@executablemd/core/api"; -import type { AgentPromptEvent } from "@executablemd/core/api"; +import { Component } from "@executablemd/core/api"; +import { Agent } from "@executablemd/agent/api"; +import type { AgentPromptEvent } from "@executablemd/agent/api"; import type { Stream } from "effection"; import { z } from "zod"; diff --git a/examples/adversarial-implementation/tests/production-components/NativeGuide.ts b/examples/adversarial-implementation/tests/production-components/NativeGuide.ts index 0c16ca9e3..b53748c07 100644 --- a/examples/adversarial-implementation/tests/production-components/NativeGuide.ts +++ b/examples/adversarial-implementation/tests/production-components/NativeGuide.ts @@ -1,4 +1,5 @@ -import { Agent, Component } from "@executablemd/core/api"; +import { Component } from "@executablemd/core/api"; +import { Agent } from "@executablemd/agent/api"; import { ensureDir, rm } from "@effectionx/fs"; import { z } from "zod"; import { read, write } from "../../components/Ticket/text-storage.ts"; diff --git a/examples/agent-certification/observe.ts b/examples/agent-certification/observe.ts index 7e97dad62..becaf2eaa 100644 --- a/examples/agent-certification/observe.ts +++ b/examples/agent-certification/observe.ts @@ -1,6 +1,7 @@ import { nativeAdapterFor } from "@executablemd/acp"; -import { Agent, Component, configurationOf, sessionOf } from "@executablemd/core"; -import type { AgentPromptEvent } from "@executablemd/core"; +import { Component } from "@executablemd/core"; +import { Agent, configurationOf, sessionOf } from "@executablemd/agent/api"; +import type { AgentPromptEvent } from "@executablemd/agent/api"; import { scoped, Err, Ok, useScope, spawn, sleep } from "effection"; import type { Result, Operation, Stream, Task } from "effection"; import { diff --git a/examples/agent-certification/report.ts b/examples/agent-certification/report.ts index 9f4359944..17a2e0855 100644 --- a/examples/agent-certification/report.ts +++ b/examples/agent-certification/report.ts @@ -1,4 +1,4 @@ -import type { SessionConfiguration } from "@executablemd/core"; +import type { SessionConfiguration } from "@executablemd/agent/api"; import { z } from "zod"; export const capability = z.enum([ diff --git a/examples/agent-certification/stage-runner.ts b/examples/agent-certification/stage-runner.ts index 629e8328e..fe0857c11 100644 --- a/examples/agent-certification/stage-runner.ts +++ b/examples/agent-certification/stage-runner.ts @@ -1,4 +1,5 @@ -import { agentIdentityComponents, Agent } from "@executablemd/core"; +import { Agent } from "@executablemd/agent/api"; +import { agentIdentityComponents } from "@executablemd/agent/host"; import { executeInstalled } from "@executablemd/core/host"; import type { HostExecution } from "@executablemd/core/host"; import { InMemoryStream } from "@executablemd/durable-streams"; diff --git a/examples/agent-usage/calibrate.ts b/examples/agent-usage/calibrate.ts index 5b8389d16..8aaf20ab6 100644 --- a/examples/agent-usage/calibrate.ts +++ b/examples/agent-usage/calibrate.ts @@ -18,7 +18,7 @@ import { homedir } from "node:os"; import { dirname, join, resolve } from "node:path"; import { fileURLToPath } from "node:url"; import process from "node:process"; -import type { PromptUsage } from "@executablemd/core"; +import type { PromptUsage } from "@executablemd/agent/api"; import { ALLOWANCE, HELP, parseSelection, Refusal } from "./selection.ts"; import type { Selection } from "./selection.ts"; import { diff --git a/examples/agent-usage/evidence.ts b/examples/agent-usage/evidence.ts index 8d015cb4a..319460819 100644 --- a/examples/agent-usage/evidence.ts +++ b/examples/agent-usage/evidence.ts @@ -2,9 +2,9 @@ import { exists, readdir, readTextFile } from "@effectionx/fs"; import type { Operation } from "effection"; import { join, resolve } from "node:path"; import { parseDurableEvent } from "@executablemd/durable-streams"; -import { AGENT_PROMPT, parsePromptRecord } from "@executablemd/core/host"; -import type { PromptRecord } from "@executablemd/core/host"; -import type { PromptUsage, ReportedTokens, UsageReading } from "@executablemd/core"; +import { AGENT_PROMPT, parsePromptRecord } from "@executablemd/agent/host"; +import type { PromptRecord } from "@executablemd/agent/host"; +import type { PromptUsage, ReportedTokens, UsageReading } from "@executablemd/agent/api"; /** How one check came out. */ export type Outcome = "verified" | "limited" | "unavailable" | "failed" | "not_run"; diff --git a/examples/agent-usage/report.ts b/examples/agent-usage/report.ts index 856af1da0..6134698ff 100644 --- a/examples/agent-usage/report.ts +++ b/examples/agent-usage/report.ts @@ -1,4 +1,4 @@ -import type { UsageCoverage, UsageReading } from "@executablemd/core"; +import type { UsageCoverage, UsageReading } from "@executablemd/agent/api"; import type { Check } from "./evidence.ts"; /** One acknowledged Prompt, as the shareable report states it. */ diff --git a/examples/repl-bench/lib/scripted-sidekick.ts b/examples/repl-bench/lib/scripted-sidekick.ts index d6e71a610..2db5bd859 100644 --- a/examples/repl-bench/lib/scripted-sidekick.ts +++ b/examples/repl-bench/lib/scripted-sidekick.ts @@ -1,7 +1,7 @@ import { createAcpxProvider, createAcpxSessionStore } from "@executablemd/acp"; import { Plugin } from "@executablemd/core/api"; -import { registerAgentProvider } from "@executablemd/core"; -import { installInvocationAgentProvider } from "@executablemd/core/host"; +import { registerAgentProvider } from "@executablemd/agent/api"; +import { installInvocationAgentProvider } from "@executablemd/agent/host"; import type { ReplPluginInstallation } from "@executablemd/cli/api"; import { env, readTextFile } from "@executablemd/runtime"; import { useTestAgentController } from "@executablemd/test-agent"; diff --git a/examples/repl-bench/lib/wheel-permission.ts b/examples/repl-bench/lib/wheel-permission.ts index cc41eea6a..0babb68a4 100644 --- a/examples/repl-bench/lib/wheel-permission.ts +++ b/examples/repl-bench/lib/wheel-permission.ts @@ -1,5 +1,5 @@ import { createAcpxProvider } from "@executablemd/acp"; -import { registerAgentProvider } from "@executablemd/core"; +import { registerAgentProvider } from "@executablemd/agent/api"; import { Plugin } from "@executablemd/core/api"; import { createFakeAcp, diff --git a/examples/repl-plugins/counter.ts b/examples/repl-plugins/counter.ts index 162580796..8d0d7d71b 100644 --- a/examples/repl-plugins/counter.ts +++ b/examples/repl-plugins/counter.ts @@ -1,7 +1,8 @@ import { createContext } from "effection"; import type { Operation } from "effection"; import { contributeDocumentation, packageDocumentation } from "@executablemd/core"; -import { AgentConversationProvider, Plugin } from "@executablemd/core/api"; +import { Plugin } from "@executablemd/core/api"; +import { AgentConversationProvider } from "@executablemd/agent/api"; import type { ReplPluginInstallation } from "@executablemd/cli/api"; const Counter = createContext<{ count: number }>("example.repl.counter"); diff --git a/knip.json b/knip.json index af107ae42..320057f2f 100644 --- a/knip.json +++ b/knip.json @@ -25,6 +25,8 @@ "paths": { "@executablemd/acp": ["packages/acp/mod.ts"], "@executablemd/acp/embedded-adapters": ["packages/acp/embedded-adapters.ts"], + "@executablemd/agent/api": ["packages/agent/api.ts"], + "@executablemd/agent/host": ["packages/agent/host.ts"], "@executablemd/cli": ["packages/cli/src/deno.ts"], "@executablemd/cli/api": ["packages/cli/api.ts"], "@executablemd/core": ["packages/core/mod.ts"], @@ -66,6 +68,8 @@ "paths": { "@executablemd/acp": ["../../packages/acp/mod.ts"], "@executablemd/acp/embedded-adapters": ["../../packages/acp/embedded-adapters.ts"], + "@executablemd/agent/api": ["../../packages/agent/api.ts"], + "@executablemd/agent/host": ["../../packages/agent/host.ts"], "@executablemd/cli": ["../../packages/cli/src/deno.ts"], "@executablemd/cli/api": ["../../packages/cli/api.ts"], "@executablemd/core": ["../../packages/core/mod.ts"], diff --git a/package.json b/package.json index aa327e29f..6e006f885 100644 --- a/package.json +++ b/package.json @@ -53,6 +53,7 @@ "devDependencies": { "@durable-streams/server": "^0.3.8", "@executablemd/acp": "workspace:*", + "@executablemd/agent": "workspace:*", "@executablemd/cli": "workspace:*", "@executablemd/core": "workspace:*", "@executablemd/durable-streams": "workspace:*", diff --git a/packages/acp/package.json b/packages/acp/package.json index 826a01d9b..98d7ea1c7 100644 --- a/packages/acp/package.json +++ b/packages/acp/package.json @@ -9,6 +9,7 @@ }, "dependencies": { "@agentclientprotocol/sdk": "1.9.0", + "@executablemd/agent": "workspace:*", "@executablemd/core": "workspace:*", "@executablemd/runtime": "workspace:*", "@openclaw/fs-safe": "0.27.0", diff --git a/packages/acp/src/checkpoint.ts b/packages/acp/src/checkpoint.ts index 0e6eda6b0..ae3d0dc04 100644 --- a/packages/acp/src/checkpoint.ts +++ b/packages/acp/src/checkpoint.ts @@ -11,7 +11,7 @@ * without UUID validation or normalization. */ -import type { AgentPromptCheckpoint } from "@executablemd/core"; +import type { AgentPromptCheckpoint } from "@executablemd/agent/api"; import type { AcpRuntimeTurnResult } from "./acpx-runtime.ts"; interface RecognizedNamespace { diff --git a/packages/acp/src/events.ts b/packages/acp/src/events.ts index 159bef825..79ee0d34c 100644 --- a/packages/acp/src/events.ts +++ b/packages/acp/src/events.ts @@ -24,7 +24,7 @@ import { each, race, stream, until } from "effection"; import type { Channel, Operation } from "effection"; -import type { AgentPromptCheckpoint, AgentPromptEvent, Session } from "@executablemd/core"; +import type { AgentPromptCheckpoint, AgentPromptEvent, Session } from "@executablemd/agent/api"; import type { AcpRuntimeTurn, AcpRuntimeTurnResult } from "./acpx-runtime.ts"; import { checkpointFromResult } from "./checkpoint.ts"; import { XmdResponse, XMD_RESPONSE, xmdPromptEvent } from "./xmd-response.ts"; diff --git a/packages/acp/src/native-launch.ts b/packages/acp/src/native-launch.ts index c359d9442..7974bec19 100644 --- a/packages/acp/src/native-launch.ts +++ b/packages/acp/src/native-launch.ts @@ -16,7 +16,7 @@ */ import { randomUUID } from "node:crypto"; -import type { IdentityProvenance } from "@executablemd/core"; +import type { IdentityProvenance } from "@executablemd/agent/api"; /** * What an adapter knows about the build behind its executable. diff --git a/packages/acp/src/permission-bridge.ts b/packages/acp/src/permission-bridge.ts index fb3ce932a..887c3d10b 100644 --- a/packages/acp/src/permission-bridge.ts +++ b/packages/acp/src/permission-bridge.ts @@ -38,8 +38,9 @@ import { ensure, Err, Ok, on, race, withResolvers } from "effection"; import type { Operation, Result, Scope, Task } from "effection"; import { z } from "zod"; -import { Agent, prepareElicitation, runPreparedElicitation } from "@executablemd/core"; -import type { PermissionOption, PermissionRequest, Session } from "@executablemd/core"; +import { prepareElicitation, runPreparedElicitation } from "@executablemd/core"; +import { Agent } from "@executablemd/agent/api"; +import type { PermissionOption, PermissionRequest, Session } from "@executablemd/agent/api"; import type { AcpPermissionDecision, AcpPermissionRequest, diff --git a/packages/acp/src/provider.ts b/packages/acp/src/provider.ts index fd4ccb09c..37b9333a1 100644 --- a/packages/acp/src/provider.ts +++ b/packages/acp/src/provider.ts @@ -39,19 +39,19 @@ import { createHash, randomUUID } from "node:crypto"; import { homedir, tmpdir } from "node:os"; import { mkdtemp, rm, writeFile } from "node:fs/promises"; import { join, resolve } from "node:path"; +import { parseJson } from "@executablemd/core"; import { Agent, claimsConfiguration, isSessionUse, - parseJson, sameExecutableBuild, sessionOf, -} from "@executablemd/core"; -import { AgentConversationProvider } from "@executablemd/core/api"; +} from "@executablemd/agent/api"; +import { AgentConversationProvider } from "@executablemd/agent/api"; +import type { JsonObject } from "@executablemd/core"; import type { ExecutableBuildBindingV1, AgentOptions, - JsonObject, ProviderSessionConfiguration, AgentOptionsRequest, AgentSessionRequest, @@ -77,7 +77,7 @@ import type { SessionConfiguration, SessionLaunchResult, UsageBuild, -} from "@executablemd/core"; +} from "@executablemd/agent/api"; import { AcpConfigurationError, applySessionConfiguration, diff --git a/packages/acp/src/session-configuration.ts b/packages/acp/src/session-configuration.ts index aee6457b8..690b541c4 100644 --- a/packages/acp/src/session-configuration.ts +++ b/packages/acp/src/session-configuration.ts @@ -18,7 +18,7 @@ import { ensure, scoped } from "effection"; import type { Operation } from "effection"; -import type { AgentOption, AgentOptionSet, SessionConfiguration } from "@executablemd/core"; +import type { AgentOption, AgentOptionSet, SessionConfiguration } from "@executablemd/agent/api"; import type { AcpRuntimeStatus } from "./acpx-runtime.ts"; /** One selector this run recognized, and the ACP id a write names it by. */ diff --git a/packages/acp/src/session-route.ts b/packages/acp/src/session-route.ts index b7b65f01e..c30af9737 100644 --- a/packages/acp/src/session-route.ts +++ b/packages/acp/src/session-route.ts @@ -15,7 +15,7 @@ import { ensure, scoped, until } from "effection"; import type { Operation } from "effection"; import { agentSessionKeyDigest } from "@executablemd/runtime"; import type { AgentSessionKey } from "@executablemd/runtime"; -import type { ExecutableBuildBindingV1 } from "@executablemd/core"; +import type { ExecutableBuildBindingV1 } from "@executablemd/agent/api"; /** * The exact V1 record. diff --git a/packages/acp/src/usage.ts b/packages/acp/src/usage.ts index ee5179338..6c954ef3e 100644 --- a/packages/acp/src/usage.ts +++ b/packages/acp/src/usage.ts @@ -25,7 +25,7 @@ import type { UsageBuild, UsageProvenance, UsageReading, -} from "@executablemd/core"; +} from "@executablemd/agent/api"; import type { AcpRuntimeEvent, AcpRuntimeQuotaTokens, diff --git a/packages/acp/src/xmd-response.ts b/packages/acp/src/xmd-response.ts index 363529c05..229233b25 100644 --- a/packages/acp/src/xmd-response.ts +++ b/packages/acp/src/xmd-response.ts @@ -1,5 +1,5 @@ import { z } from "zod"; -import type { AgentPromptEvent } from "@executablemd/core"; +import type { AgentPromptEvent } from "@executablemd/agent/api"; const identity: z.ZodString = z.string().min(1).max(512); const json: z.ZodJSONSchema = z.json(); diff --git a/packages/acp/tests/acceptance.test.ts b/packages/acp/tests/acceptance.test.ts index dd21aad01..2350ed8b6 100644 --- a/packages/acp/tests/acceptance.test.ts +++ b/packages/acp/tests/acceptance.test.ts @@ -10,9 +10,10 @@ import { ensureDir, rm, writeTextFile } from "@effectionx/fs"; import { randomUUID } from "node:crypto"; import * as path from "node:path"; import * as os from "node:os"; -import { agentIdentityComponents, Agent, installAgentComponents } from "@executablemd/core"; +import { Agent } from "@executablemd/agent/api"; +import { agentIdentityComponents, installAgentComponents } from "@executablemd/agent/host"; import { executeInstalled } from "@executablemd/core/host"; -import type { AgentSessionRequest } from "@executablemd/core"; +import type { AgentSessionRequest } from "@executablemd/agent/api"; import { InMemoryStream } from "@executablemd/durable-streams"; import { createAcpxProvider } from "../mod.ts"; import { createFakeRuntime, makeRegistry, makeStore, useFlatWorld } from "./helpers.ts"; diff --git a/packages/acp/tests/acpx-materialization.test.ts b/packages/acp/tests/acpx-materialization.test.ts index ab38655ee..7fb758d7c 100644 --- a/packages/acp/tests/acpx-materialization.test.ts +++ b/packages/acp/tests/acpx-materialization.test.ts @@ -31,8 +31,8 @@ import { chmod } from "node:fs/promises"; import { randomUUID } from "node:crypto"; import * as os from "node:os"; import * as path from "node:path"; -import type { AgentPromptEvent } from "@executablemd/core"; -import { Agent } from "@executablemd/core"; +import type { AgentPromptEvent } from "@executablemd/agent/api"; +import { Agent } from "@executablemd/agent/api"; import { createAcpRuntime } from "../src/acpx-runtime.ts"; import { useAcpxProvider } from "../src/provider.ts"; import { retainedSession } from "../src/session-store.ts"; diff --git a/packages/acp/tests/agent-certification.test.ts b/packages/acp/tests/agent-certification.test.ts index 11233acce..f1ba5c1ee 100644 --- a/packages/acp/tests/agent-certification.test.ts +++ b/packages/acp/tests/agent-certification.test.ts @@ -6,13 +6,10 @@ import { writeTextFile } from "@effectionx/fs"; import { join } from "node:path"; import { settleStage } from "../../../examples/agent-certification/stage-runner.ts"; import { randomUUID } from "node:crypto"; -import { - Agent, - agentIdentityComponents, - installAgentComponents, - useNormalizedOutput, -} from "@executablemd/core"; -import type { AgentPromptEvent } from "@executablemd/core"; +import { useNormalizedOutput } from "@executablemd/core"; +import { Agent } from "@executablemd/agent/api"; +import { agentIdentityComponents, installAgentComponents } from "@executablemd/agent/host"; +import type { AgentPromptEvent } from "@executablemd/agent/api"; import { executeInstalled } from "@executablemd/core/host"; import { InMemoryStream } from "@executablemd/durable-streams"; import { createAcpRuntime, createAcpxProvider, createAcpxSessionStore } from "../mod.ts"; diff --git a/packages/acp/tests/claude-reconnect.test.ts b/packages/acp/tests/claude-reconnect.test.ts index 3a77ec612..41a4bb16f 100644 --- a/packages/acp/tests/claude-reconnect.test.ts +++ b/packages/acp/tests/claude-reconnect.test.ts @@ -31,10 +31,14 @@ import type { } from "../src/acpx-runtime.ts"; import { createEmbeddedAdapters } from "../src/adapter-snapshots.ts"; import type { EmbeddedAdapters } from "../src/adapter-snapshots.ts"; -import { Agent, sessionOf } from "@executablemd/core"; -import type { AgentLaunchCoordinator, Session, SessionConfiguration } from "@executablemd/core"; -import { openSessionRequest } from "../../core/src/agent/session-request.ts"; -import { createSessionSetupOwner } from "../../core/src/agent/session-setup.ts"; +import { Agent, sessionOf } from "@executablemd/agent/api"; +import type { + AgentLaunchCoordinator, + Session, + SessionConfiguration, +} from "@executablemd/agent/api"; +import { openSessionRequest } from "../../agent/src/session-request.ts"; +import { createSessionSetupOwner } from "../../agent/src/session-setup.ts"; import { createAcpxProvider } from "../src/provider.ts"; import { makeCoordinator, makeRegistry, useFlatWorld } from "./helpers.ts"; diff --git a/packages/acp/tests/host-conversation.test.ts b/packages/acp/tests/host-conversation.test.ts index 07cfaaf23..9c39891fc 100644 --- a/packages/acp/tests/host-conversation.test.ts +++ b/packages/acp/tests/host-conversation.test.ts @@ -2,7 +2,7 @@ * Tier HC — one host conversation over the canonical ACP provider. * * `useAgentConversation()` is proven against a stub provider in - * `packages/core/tests/agent-conversation.test.ts`, where a stub is the right + * `packages/agent/tests/agent-conversation.test.ts`, where a stub is the right * instrument: those rows are about what the conversation does with what a * provider says. One thing a stub cannot show is the *order* the canonical * provider commits in — the adapter accepts the session, the provider's own @@ -33,10 +33,14 @@ import { import type { DurableEvent } from "@executablemd/durable-streams"; import { Ok, scoped, spawn, suspend, until, withResolvers } from "effection"; import type { Operation, Result } from "effection"; -import { Agent, Component, installAgentComponents } from "@executablemd/core"; -import type { FunctionComponentDefinition, Json, Session } from "@executablemd/core"; -import { useAgentConversation } from "@executablemd/core/host"; -import type { AgentConversation, ExecutionInstallation } from "@executablemd/core/host"; +import { Component } from "@executablemd/core"; +import { Agent } from "@executablemd/agent/api"; +import { installAgentComponents } from "@executablemd/agent/host"; +import type { FunctionComponentDefinition, Json } from "@executablemd/core"; +import type { Session } from "@executablemd/agent/api"; +import { useAgentConversation } from "@executablemd/agent/host"; +import type { ExecutionInstallation } from "@executablemd/core/host"; +import type { AgentConversation } from "@executablemd/agent/host"; import { createAcpxSessionStore } from "../src/session-store.ts"; import { withCertificationFixture } from "./certification-fixture.ts"; @@ -55,7 +59,7 @@ import type { NativeAdapter } from "../src/native-launch.ts"; import { createMemorySessionRouteStore } from "../src/session-route.ts"; import type { AgentSessionRouteStore } from "../src/session-route.ts"; import { deriveSessionKey } from "../src/session-key.ts"; -import type { AgentSessionRequest } from "@executablemd/core/api"; +import type { AgentSessionRequest } from "@executablemd/agent/api"; import { createFakeObserver, createFakeRuntime, diff --git a/packages/acp/tests/loaded-copy.test.ts b/packages/acp/tests/loaded-copy.test.ts index ff2ff254c..34f62e0a6 100644 --- a/packages/acp/tests/loaded-copy.test.ts +++ b/packages/acp/tests/loaded-copy.test.ts @@ -28,11 +28,11 @@ import type { Operation, Result } from "effection"; import { ensureDir, rm, writeTextFile } from "@effectionx/fs"; import { exec } from "@effectionx/process"; import { mkdtemp } from "node:fs/promises"; -import { join } from "node:path"; +import { dirname, join } from "node:path"; import { tmpdir } from "node:os"; import process from "node:process"; import { fileURLToPath } from "node:url"; -import { Agent } from "@executablemd/core"; +import { Agent } from "@executablemd/agent/api"; import type { AgentLaunchCoordinator, AgentSessionSetup, @@ -40,7 +40,7 @@ import type { Session, SessionConfiguration, AgentProviderFactory, -} from "@executablemd/core"; +} from "@executablemd/agent/api"; import { InMemoryStream } from "@executablemd/durable-streams"; import { world } from "./released-peer.ts"; import { retainedSession } from "../src/session-store.ts"; @@ -48,7 +48,7 @@ import { readTextFile } from "@effectionx/fs"; import { createAcpxProvider } from "../src/provider.ts"; // This run's own copy, for the case that needs a canonical owner to refuse a // foreign request. -import { createSessionSetupOwner } from "../../core/src/agent/session-setup.ts"; +import { createSessionSetupOwner } from "../../agent/src/session-setup.ts"; import { createFakeRuntime, makeRecord, @@ -62,7 +62,7 @@ import type { FakeRuntimeHarness } from "./helpers.ts"; const CWD = "/work"; const REPOSITORY = fileURLToPath(new URL("../../..", import.meta.url)); -const CORE_AGENT = fileURLToPath(new URL("../../core/src/agent/", import.meta.url)); +const AGENT = fileURLToPath(new URL("../../agent/", import.meta.url)); /** * What this suite asks of the other copy, and what it will accept as an answer. @@ -331,10 +331,10 @@ function useForeignCore(): Operation { entry, [ `export { openSessionRequest } from ${JSON.stringify( - join(CORE_AGENT, "session-request.ts"), + join(AGENT, "src/session-request.ts"), )};`, `export { createSessionSetupOwner } from ${JSON.stringify( - join(CORE_AGENT, "session-setup.ts"), + join(AGENT, "src/session-setup.ts"), )};`, "", ].join("\n"), @@ -454,6 +454,44 @@ function refusalOf(operation: () => Operation): Operation { })(); } +/** + * Core's terminal renderer, which the Agent package's public entries reach + * through Core's root. + * + * `deno bundle` cannot bundle it: its emoji dependency loads JSON through an + * extensionless `require`. So the consumer bundle leaves it external, and the + * one import of it is pointed at the npm specifier Core's own manifest names, + * which this frozen workspace already resolves. Agent and Core themselves are + * still bundled, so the Session capability is still a separate copy. + */ +const TERMINAL_RENDERER = "marked-terminal"; + +function* loadRendererFromItsPackage(bundle: string): Operation { + const manifest: unknown = JSON.parse( + yield* readTextFile(join(REPOSITORY, "packages/core/deno.json")), + ); + const imports = + typeof manifest === "object" && manifest !== null + ? Reflect.get(manifest, "imports") + : undefined; + const specifier = + typeof imports === "object" && imports !== null + ? Reflect.get(imports, TERMINAL_RENDERER) + : undefined; + if (typeof specifier !== "string" || !specifier.startsWith("npm:")) { + throw new Error(`packages/core/deno.json names no npm specifier for ${TERMINAL_RENDERER}`); + } + const external = `from ${JSON.stringify(TERMINAL_RENDERER)};`; + const text = yield* readTextFile(bundle); + const occurrences = text.split(external).length - 1; + if (occurrences !== 1) { + throw new Error( + `the consumer bundle imports ${TERMINAL_RENDERER} ${occurrences} times, not once`, + ); + } + yield* writeTextFile(bundle, text.replace(external, `from ${JSON.stringify(specifier)};`)); +} + function useForeignPublicConsumer(): Operation< ( factory: AgentProviderFactory, @@ -471,21 +509,23 @@ function useForeignPublicConsumer(): Operation< yield* ensure(() => rm(directory, { recursive: true, force: true })); const entry = join(directory, "entry.ts"); const bundle = join(directory, "core.js"); - for (const path of ["components/components.md", "agent/components.md"]) { - const target = join(directory, path); - yield* ensureDir(join(directory, path.split("/")[0]!)); - yield* writeTextFile( - target, - yield* readTextFile(join(REPOSITORY, "packages/core/src", path)), - ); + // A bundle's `import.meta.url` is the bundle's own, so each package's + // documentation is staged where its module looks beside that file: core's + // beneath `components/`, the Agent package's directly beside it. + for (const [source, staged] of [ + ["packages/core/src/components/components.md", "components/components.md"], + ["packages/agent/src/components.md", "components.md"], + ] as const) { + const target = join(directory, staged); + yield* ensureDir(dirname(target)); + yield* writeTextFile(target, yield* readTextFile(join(REPOSITORY, source))); } yield* writeTextFile( entry, ` - import { Agent } from ${JSON.stringify(join(CORE_AGENT, "agent-api.ts"))}; - import { installAgentComponents, agentIdentityComponents } from ${JSON.stringify(join(CORE_AGENT, "components.ts"))}; + import { Agent, configurationOf } from ${JSON.stringify(join(AGENT, "api.ts"))}; + import { installAgentComponents, agentIdentityComponents } from ${JSON.stringify(join(AGENT, "host.ts"))}; import { useNormalizedOutput } from ${JSON.stringify(join(REPOSITORY, "packages/core/src/output/normalize.ts"))}; - import { configurationOf } from ${JSON.stringify(join(CORE_AGENT, "session-use.ts"))}; import { executeInstalled } from ${JSON.stringify(join(REPOSITORY, "packages/core/host.ts"))}; export function* run(factory, path, journal, observe) { yield* installAgentComponents({ defaultAgent: "scribe", rootProvider: { @@ -528,6 +568,7 @@ function useForeignPublicConsumer(): Operation< "--frozen", "--node-modules-dir=none", "--external=@effectionx/process", + `--external=${TERMINAL_RENDERER}`, entry, "--output", bundle, @@ -537,6 +578,7 @@ function useForeignPublicConsumer(): Operation< if (built.code !== 0) { throw new Error(`could not bundle the public Core consumer: ${built.stdout}${built.stderr}`); } + yield* loadRendererFromItsPackage(bundle); const run = methodOf>(yield* until(import(`file://${bundle}`)), "run"); if (run === undefined) { throw new Error("the other Core copy exports no public consumer"); diff --git a/packages/acp/tests/native-launch.test.ts b/packages/acp/tests/native-launch.test.ts index bc3160574..fb289ca75 100644 --- a/packages/acp/tests/native-launch.test.ts +++ b/packages/acp/tests/native-launch.test.ts @@ -12,18 +12,18 @@ * phases in order and keeps every record, so what a case reads is what the * provider produced. It deliberately validates no request — identity, lineage, * durability and settlement are core's half, and - * `packages/core/tests/agent-session-launch.test.ts` owns them. + * `packages/agent/tests/agent-session-launch.test.ts` owns them. */ import { describe, it } from "@executablemd/test-support/bdd"; import { expect } from "@executablemd/test-support/expect"; import { ensure, Ok, scoped, sleep, spawn, until, withResolvers } from "effection"; import type { Operation } from "effection"; -import { Agent, sameExecutableBuild } from "@executablemd/core"; -import type { ConfigureAgentSession, ProviderSessionConfiguration } from "@executablemd/core"; +import { Agent, sameExecutableBuild } from "@executablemd/agent/api"; +import type { ConfigureAgentSession, ProviderSessionConfiguration } from "@executablemd/agent/api"; // The engine's own session-request machinery, used the way core uses it: these // suites stand in for an installation, so they open and read requests rather // than inventing a second shape for one. -import { consumeSessionRequest, openSessionRequest } from "../../core/src/agent/session-request.ts"; +import { consumeSessionRequest, openSessionRequest } from "../../agent/src/session-request.ts"; import type { AgentLaunchRequest, AgentLaunchCoordinator, @@ -33,7 +33,7 @@ import type { PreparedLaunchRecord, Session, SessionConfiguration, -} from "@executablemd/core"; +} from "@executablemd/agent/api"; import { flushOutput, installControlledLauncher, @@ -76,7 +76,7 @@ import type { FakeRuntimeHarness, ScriptedTurn, } from "./helpers.ts"; -import type { ExecutableBuildBindingV1 } from "@executablemd/core"; +import type { ExecutableBuildBindingV1 } from "@executablemd/agent/api"; import type { AcpxSessionPolicy } from "../src/provider.ts"; import type { ExecutableObserver } from "@executablemd/runtime"; import type { AcpRuntimeEvent, AcpSessionRecord, AcpSessionStore } from "../src/acpx-runtime.ts"; diff --git a/packages/acp/tests/permission-bridge.test.ts b/packages/acp/tests/permission-bridge.test.ts index e7b18d2a4..460aa0d9c 100644 --- a/packages/acp/tests/permission-bridge.test.ts +++ b/packages/acp/tests/permission-bridge.test.ts @@ -19,8 +19,8 @@ import { withResolvers, } from "effection"; import type { Operation, Scope } from "effection"; -import { Agent } from "@executablemd/core"; -import type { Session } from "@executablemd/core"; +import { Agent } from "@executablemd/agent/api"; +import type { Session } from "@executablemd/agent/api"; import type { AcpPermissionRequest } from "../src/acpx-runtime.ts"; import { createPermissionBridge } from "../src/permission-bridge.ts"; diff --git a/packages/acp/tests/provider.test.ts b/packages/acp/tests/provider.test.ts index 1ef1f2840..81751373b 100644 --- a/packages/acp/tests/provider.test.ts +++ b/packages/acp/tests/provider.test.ts @@ -8,10 +8,11 @@ import { describe, it } from "@executablemd/test-support/bdd"; import { expect } from "@executablemd/test-support/expect"; import { scoped, sleep, spawn, until, withResolvers } from "effection"; import type { Operation } from "effection"; -import { Agent, claimsConfiguration, Config, sessionOf } from "@executablemd/core"; -import type { ConfigureAgentSession } from "@executablemd/core"; -import { openSessionRequest } from "../../core/src/agent/session-request.ts"; -import { createSessionSetupOwner } from "../../core/src/agent/session-setup.ts"; +import { Config } from "@executablemd/core"; +import { Agent, claimsConfiguration, sessionOf } from "@executablemd/agent/api"; +import type { ConfigureAgentSession } from "@executablemd/agent/api"; +import { openSessionRequest } from "../../agent/src/session-request.ts"; +import { createSessionSetupOwner } from "../../agent/src/session-setup.ts"; import type { AgentLaunchRequest, AgentPromptEvent, @@ -22,7 +23,7 @@ import type { SessionConfiguration, PromptUsage, UsageBuild, -} from "@executablemd/core"; +} from "@executablemd/agent/api"; import { AcpxSessionPolicyError, createAcpxProvider, diff --git a/packages/acp/tests/released-runtime.test.ts b/packages/acp/tests/released-runtime.test.ts index 6ed9a36d1..d8d339cc7 100644 --- a/packages/acp/tests/released-runtime.test.ts +++ b/packages/acp/tests/released-runtime.test.ts @@ -28,14 +28,10 @@ import type { } from "../src/acpx-runtime.ts"; import { retainedSession } from "../src/session-store.ts"; import { createAcpxProvider } from "../src/provider.ts"; -import { - Agent, - agentIdentityComponents, - installAgentComponents, - useNormalizedOutput, - configurationOf, -} from "@executablemd/core"; -import type { AgentPromptEvent, Session } from "@executablemd/core"; +import { useNormalizedOutput } from "@executablemd/core"; +import { Agent, configurationOf } from "@executablemd/agent/api"; +import { agentIdentityComponents, installAgentComponents } from "@executablemd/agent/host"; +import type { AgentPromptEvent, Session } from "@executablemd/agent/api"; import { executeInstalled } from "@executablemd/core/host"; import { InMemoryStream } from "@executablemd/durable-streams"; import { applySessionConfiguration } from "../src/session-configuration.ts"; @@ -576,7 +572,7 @@ describe( mode: "prompt", requestId: text, }); - const channel = createChannel(); + const channel = createChannel(); const subscription = yield* channel; const checkpoints: unknown[] = []; yield* spawn(() => diff --git a/packages/acp/tests/session-route.test.ts b/packages/acp/tests/session-route.test.ts index e6646a9dc..9d8cd3ea8 100644 --- a/packages/acp/tests/session-route.test.ts +++ b/packages/acp/tests/session-route.test.ts @@ -39,7 +39,7 @@ import type { AgentSessionRouteV2, AgentSessionRouteV3, } from "../src/session-route.ts"; -import type { ExecutableBuildBindingV1 } from "@executablemd/core"; +import type { ExecutableBuildBindingV1 } from "@executablemd/agent/api"; import { cliBase } from "@executablemd/test-support/launch"; const KEY: AgentSessionKey = { diff --git a/packages/agent/api.ts b/packages/agent/api.ts new file mode 100644 index 000000000..18cd01469 --- /dev/null +++ b/packages/agent/api.ts @@ -0,0 +1,178 @@ +/** + * @module + * + * The consumer API of `@executablemd/agent`: the contextual Agent operations a + * Plugin composes around, the operations a provider and an author's own code + * reach, and the contracts they are written in. + * + * ```ts + * import { Agent } from "@executablemd/agent/api"; + * import { Plugin } from "@executablemd/core/api"; + * + * export default Plugin({ + * name: "example", + * *install() { + * yield* Agent.around({ + * *prompt([content, options], next) { + * return yield* next(`Be brief.\n\n${content}`, options); + * }, + * }); + * return undefined; + * }, + * }); + * ``` + * + * `Plugin`, `Execution` and the rest of the generic execution surface stay in + * `@executablemd/core/api`. What a host installs — the Agent vocabulary, a + * provider for a region it projects, held conversations and the readers of + * retained Prompts — is in `@executablemd/agent/host`. + */ + +/** + * The Agent Api, and the contracts its operations are written in. + * + * A Plugin composes agent work the same way it composes a document: around + * these operations, in the ordinary order. What it reaches here is + * provider-neutral — exact choice IDs, normalized options, and the session a + * provider issued — and never a protocol type belonging to whichever provider + * happens to be installed. + */ +export { Agent } from "./src/agent-api.ts"; +// The one deny decision, so a host writing its own permission policy reaches +// the same rule the base handler and every built-in policy reach rather than +// spelling "reject_once, then reject_always, otherwise cancel" again. +export { denyPermission } from "./src/agent-api.ts"; +export type { + AgentApi, + AgentOption, + AgentOptions, + AgentOptionSet, + AgentOptionsRequest, + AgentPromptEvent, + PromptImage, + LaunchOptions, + PermissionMode, + PermissionOption, + PermissionOutcome, + PermissionRequest, + PromptOptions, + Session, + SessionIdentity, + SessionConfiguration, + SessionLaunchResult, +} from "./src/agent-api.ts"; +export { AgentPromptError } from "./src/errors.ts"; +/** + * The opaque session request a `` element routes. A handler reads its + * descriptive name; only the delivered launch coordinator reads the engine identity. + */ +export { AgentSessionProtocolError, isSessionRequest } from "./src/session-request.ts"; +export type { AgentSessionRequest } from "./src/session-request.ts"; +/** + * The provider a retained conversation does its work through. + * + * Here, beside `Agent`, because it is the other half of the same boundary: a + * host that serves saved conversations installs this object in its provider's + * own scope, and the conversation reads it once in its own. Ordinary `` + * and `` keep composing through `Agent`, which is what middleware is + * for; a chat does not, because what holds it to the configuration it was + * created under cannot be something a handler may route around. + * + * A held turn is captured here and reached through this object's own receiver. + * Its content and cold stream are composed by ordinary outer `Agent.prompt` + * middleware above a turn-local terminal bound to this provider, the selected + * agent and the exact checked Session — so composition changes the text and the + * stream, never which provider answers. What this provider receives is the text + * the journal retains; a composition that changed the checked call is refused + * before any native work, and nothing routes through ordinary provider handlers + * as a fallback. Subscription-owned cleanup belongs to that conversation's turn. + * + * One name for the interface and the Context, as `Agent` already has. + */ +export { AgentConversationProvider } from "./src/conversation-provider.ts"; +/** + * One authentic use of a conversation, and what a reader may ask about one. + * + * A use is a `Session`, so nothing composing around these operations has to + * know about it. `claimsConfiguration()` answers for any value; `isSessionUse()`, + * `sessionOf()` and `configurationOf()` answer for a value this build issued, + * and refuse a rebuilt, copied or foreign one rather than reading it as an + * ordinary session. + * + * Reading is not acting. Which installation a use belongs to, and whether it is + * the one this operation was authored with, are settled where the operation + * reaches the provider — through the coordinator this package delivers there. + * So a handler may see what a use says and delegate it, and still cannot pair a + * conversation with settings of its own. + * + * Issuing one is `useConfiguredSession()`, which is the only way one comes into + * being. + */ +export { + AgentSessionUseError, + claimsConfiguration, + configurationOf, + isSessionUse, + sessionOf, +} from "./src/session-use.ts"; +export type { AgentSessionUse } from "./src/session-use.ts"; +export { useConfiguredSession } from "./src/launch-install.ts"; +// Native session launch — the records one launch retains, and the request its +// public route carries. What runs and retains a phase is not here +// and is not anywhere: it is delivered to the selected provider. +export { AgentLaunchError, sameExecutableBuild } from "./src/launch.ts"; +export type { + DetachedLaunchRecord, + ExecutableBuildBindingV1, + ExitedLaunchRecord, + IdentityProvenance, + InstructionReconciliation, + LaunchFailure, + LaunchFailureClass, + LaunchPhase, + LaunchRecord, + MaterializationPlan, + MaterializationUsage, + MaterializedLaunchRecord, + PreparedLaunchRecord, +} from "./src/launch.ts"; +export { AgentLaunchProtocolError } from "./src/launch-request.ts"; +export type { AgentLaunchRequest } from "./src/launch-request.ts"; +export type { AgentLaunchPhases, AgentLaunchCoordinator } from "./src/launch-coordinator.ts"; +export { launchAgentSession } from "./src/launch-install.ts"; +// What a provider reports through the coordinator's optional usage receiver, +// and what a canonical Prompt record retains of it. +export type { + PromptUsage, + PromptUsageReporter, + ReportedTokens, + UsageBuild, + UsageCoverage, + UsageProvenance, + UsageReading, +} from "./src/usage.ts"; +// What settles one session setup. A provider receives the handle through the +// coordinator delivered to its factory; the types are here so it can name them. +export type { + AgentSessionSetup, + AgentSessionSetupState, + ConfigureAgentSession, + ProviderSessionConfiguration, +} from "./src/session-setup.ts"; +// The checkpoint type, because the coordinator's signature names it. The carrier +// itself is exported from nowhere: writing one is reachable only through a +// delivered coordinator, and reading one only from the prompt this package is +// running. +export { AgentPromptCheckpointError } from "./src/checkpoint.ts"; +export type { AgentPromptCheckpoint } from "./src/checkpoint.ts"; +// `installAgentProvider` is deliberately absent: it takes a launch coordinator, +// and a coordinator reachable by import is one every package and every loaded +// copy can reach. A host installs a registered provider through +// `useProviderInstallation()` from `./host`, which mints one and delivers it +// privately to the factory through this invocation's terminal. +export { AgentProviders, registerAgentProvider } from "./src/provider-api.ts"; +export type { + AgentProviderApi, + AgentProviderFactory, + AgentProviderOptions, +} from "./src/provider-api.ts"; diff --git a/packages/agent/deno.json b/packages/agent/deno.json new file mode 100644 index 000000000..1f9f67b00 --- /dev/null +++ b/packages/agent/deno.json @@ -0,0 +1,12 @@ +{ + "name": "@executablemd/agent", + "version": "0.14.1", + "exports": { + "./api": "./api.ts", + "./host": "./host.ts" + }, + "imports": { + "@effectionx/context-api": "npm:@effectionx/context-api@0.6.0", + "zod": "npm:zod@^4.3.6" + } +} diff --git a/packages/agent/host.ts b/packages/agent/host.ts new file mode 100644 index 000000000..5a6029058 --- /dev/null +++ b/packages/agent/host.ts @@ -0,0 +1,136 @@ +/** + * @module + * + * The host boundary of `@executablemd/agent`: what a distribution's own host + * installs to give an execution the Agent vocabulary, and what it reads back + * from a retained journal. + * + * ```ts + * import { installAgentComponents } from "@executablemd/agent/host"; + * + * // In the host's own setup, in the scope its execution runs in: + * yield* installAgentComponents({ defaultAgent: "claude" }); + * ``` + * + * Core by itself contributes no Agent registrations. A host that installs this + * package's components gets ``, ``, ``, + * ``, ``, `` and `` under + * the same component origin, documentation owner and durable identities core + * used before the package existed, so retained journals and authored documents + * read the same. + * + * Kept apart from `./api` for the reason core keeps its own `./host`: nothing a + * document, a component or a middleware package reaches by importing the + * consumer API can install a provider for a region it did not author, decide + * where a prompt is journaled, or answer a withheld reply. + */ + +// Agent components — // over a provider-factory seam. +export { + AGENT_REGISTRATIONS, + agentDocumentation, + agentIdentityComponents, + installAgentComponents, + useAgentComponents, +} from "./src/components.ts"; +export type { AgentComponentsOptions } from "./src/components.ts"; +export { + installApproveAll, + installApproveReads, + installAskPermission, + installPermissionMode, + installPromptFailurePolicy, +} from "./src/permission.ts"; + +/** + * Installing a registered provider. + * + * `useProviderInstallation()` mints a launch coordinator and delivers it + * privately to the provider factory through this invocation's terminal. + */ +export { useProviderInstallation } from "./src/launch-install.ts"; + +/** + * Installing one Agent provider for the invocation that projects the content it + * covers. + * + * The narrowest act of infrastructure: a trusted host component that + * establishes a constrained ceiling around content it projects installs the + * provider *in* that invocation, exactly as `` does, because a + * provider installed in a frame nested inside it would be invisible to the very + * content it was selected for. + */ +export { installInvocationAgentProvider } from "./src/launch-install.ts"; + +/** + * One retained agent conversation, run over a held execution. + * + * A root is evaluated by the execution that captured the selection it runs + * under, through `HostExecution.evaluateGeneratedXmdRoot` or the same method on + * an `AgentConversation`. + */ +export { + AgentConversationError, + AgentReplyWithheldError, + useAgentConversation, +} from "./src/conversation.ts"; +export type { AgentConversation, AgentConversationRequest } from "./src/conversation.ts"; + +/** + * Where a completed Prompt publishes, for a host that retains something beside + * it. + * + * A value the host holds and passes. An ordinary run installs none and + * publishes exactly as it always did. A host that installs one moves the + * `agent_prompt` append inside the transaction it opened, so what it keeps + * beside that event commits with the event or not at all. + */ +export { useAgentPromptPublisher } from "./src/publication.ts"; +export type { + AgentPromptAssociation, + AgentPromptHandle, + AgentPromptObservation, + AgentPromptPublication, + AgentPromptPublisher, +} from "./src/publication.ts"; + +/** + * The durable Agent Prompt record, for a host that reads a retained journal. + * + * A sealed workflow artifact classifies each Agent session by what its retained + * Prompts say, and the only thing that can answer that is the parser the live + * run already records through. A second reading of the same durable value would + * be a second contract, so the parser and the effect type it belongs to cross + * the boundary instead. + */ +export { AGENT_PROMPT, parsePromptRecord } from "./src/journal.ts"; +export type { PromptRecord } from "./src/journal.ts"; + +/** + * A withheld reply a local person accepted, and the one rule that joins it to + * its turn. + * + * Readers of a held conversation's history — replay, a Sidekick's chat and + * its passive projections — read a withheld turn followed by its acceptance as + * that turn's successful reply. They read it through this reconciler rather + * than their own, so they agree on which acceptances count. + */ +export { acceptedReplies, AGENT_PROMPT_REPLY, parsePromptReply } from "./src/reply-acceptance.ts"; +export type { PromptReplyRecord } from "./src/reply-acceptance.ts"; + +/** + * The trusted foreground question about a withheld reply. + * + * Installed by a host with a person in front of it, beside its prompt + * publisher, as one of a held conversation's installations. A host that + * installs none keeps every withheld reply withheld. See + * `src/reply-review.ts`. + */ +export { useAgentReplyReview } from "./src/reply-review.ts"; +export type { + AgentReplyDecision, + AgentReplyFinding, + AgentReplyHold, + AgentReplyReviewer, +} from "./src/reply-review.ts"; +export type { FeedbackSlice } from "./src/reply-review.ts"; diff --git a/packages/agent/package.json b/packages/agent/package.json new file mode 100644 index 000000000..3513e9301 --- /dev/null +++ b/packages/agent/package.json @@ -0,0 +1,18 @@ +{ + "name": "@executablemd/agent", + "version": "0.14.1", + "description": "Agent sessions, prompts and held conversations for executable.md documents.", + "type": "module", + "exports": { + "./api": "./api.ts", + "./host": "./host.ts" + }, + "dependencies": { + "@effectionx/context-api": "0.6.0", + "@executablemd/core": "workspace:*", + "@executablemd/durable-streams": "workspace:*", + "@executablemd/runtime": "workspace:*", + "effection": "4.1.0", + "zod": "^4.3.6" + } +} diff --git a/packages/core/src/agent/agent-api.ts b/packages/agent/src/agent-api.ts similarity index 99% rename from packages/core/src/agent/agent-api.ts rename to packages/agent/src/agent-api.ts index 116dc2166..ddc331883 100644 --- a/packages/core/src/agent/agent-api.ts +++ b/packages/agent/src/agent-api.ts @@ -116,7 +116,7 @@ export type ChildAnswerPromptEvent = | { readonly status: "invalid"; readonly reason: "schema"; - readonly issues: readonly import("../validate.ts").NormalizedIssue[]; + readonly issues: readonly import("@executablemd/core").NormalizedIssue[]; } | { readonly status: "invalid"; readonly reason: "response-format" }; } diff --git a/packages/core/src/agent/checkpoint.ts b/packages/agent/src/checkpoint.ts similarity index 100% rename from packages/core/src/agent/checkpoint.ts rename to packages/agent/src/checkpoint.ts diff --git a/packages/core/src/agent/components.md b/packages/agent/src/components.md similarity index 90% rename from packages/core/src/agent/components.md rename to packages/agent/src/components.md index e3f623277..6570618d7 100644 --- a/packages/core/src/agent/components.md +++ b/packages/agent/src/components.md @@ -1,11 +1,13 @@ -Long-form documentation for the Agent components canonical core registers. +Long-form documentation for the Agent components the `@executablemd/agent` +package registers. These are the components a document uses to talk to a coding agent: which agent and session to use, how to prompt it, how to answer the permission requests it -makes, and how to hand it the terminal. They register under -`@executablemd/core`, beside the components in `../components/components.md`, -and are documented here because this is the registration boundary they belong -to. +makes, and how to hand it the terminal. They register under the origin +`@executablemd/core`, which they kept when they moved out of core into this +package, so authored documents, retained journals and documentation lookups name +them as before. They are documented here because this package is the +registration boundary they belong to. Most of them are *regions*: they establish something for the content inside them and restore what was there on the way out. That is what lets one document use two diff --git a/packages/core/src/agent/components.ts b/packages/agent/src/components.ts similarity index 93% rename from packages/core/src/agent/components.ts rename to packages/agent/src/components.ts index 69f486ebf..fd74225cc 100644 --- a/packages/core/src/agent/components.ts +++ b/packages/agent/src/components.ts @@ -23,18 +23,23 @@ import { Err, scoped, spawn, withResolvers } from "effection"; import type { Operation, Result } from "effection"; -import { Execution } from "../execute.ts"; -import { registerComponents } from "../components/registration.ts"; -import { contributeDocumentation } from "../documentation-api.ts"; -import { packageDocumentation, packagedAssetReader } from "../component-documentation.ts"; -import type { DocumentationContribution, DocumentationReader } from "../component-documentation.ts"; -import { CORE_ORIGIN } from "../components/registry.ts"; -import { createReplayStream } from "../replay-stream.ts"; -import { documented } from "../components/documentation.ts"; -import type { ComponentRegistration } from "../components/registration.ts"; -import type { Json } from "../types.ts"; +import { + registerComponents, + contributeDocumentation, + packageDocumentation, + createReplayStream, + documented, +} from "@executablemd/core"; +import type { + DocumentationContribution, + DocumentationReader, + ComponentRegistration, + Json, +} from "@executablemd/core"; +import { Execution } from "@executablemd/core/api"; +import type { IdentityComponent } from "@executablemd/core/host"; +import { AGENT_ORIGIN } from "./origin.ts"; import { sessionComponent } from "./function-components.ts"; -import type { IdentityComponent } from "../invocation-identity.ts"; import type { PermissionMode } from "./agent-api.ts"; import type { AgentProviderFactory, AgentProviderOptions } from "./provider-api.ts"; import type { AgentLaunchCoordinator } from "./launch-coordinator.ts"; @@ -94,7 +99,7 @@ export function agentIdentityComponents(): readonly IdentityComponent[] { return [ { name: "Session", - origin: CORE_ORIGIN, + origin: AGENT_ORIGIN, props: SESSION_PROPS, ...documented({ description: @@ -123,7 +128,7 @@ export function agentIdentityComponents(): readonly IdentityComponent[] { export const AGENT_REGISTRATIONS: readonly ComponentRegistration[] = [ { name: "AgentProvider", - origin: CORE_ORIGIN, + origin: AGENT_ORIGIN, fn: AgentProvider, props: AGENT_PROVIDER_PROPS, ...documented({ @@ -138,7 +143,7 @@ export const AGENT_REGISTRATIONS: readonly ComponentRegistration[] = [ }, { name: "Agent", - origin: CORE_ORIGIN, + origin: AGENT_ORIGIN, fn: AgentComponent, props: AGENT_PROPS, ...documented({ @@ -152,7 +157,7 @@ export const AGENT_REGISTRATIONS: readonly ComponentRegistration[] = [ }, { name: "Session.Launch", - origin: CORE_ORIGIN, + origin: AGENT_ORIGIN, fn: SessionLaunch, props: SESSION_LAUNCH_PROPS, ...documented({ @@ -167,7 +172,7 @@ export const AGENT_REGISTRATIONS: readonly ComponentRegistration[] = [ }, { name: "Prompt", - origin: CORE_ORIGIN, + origin: AGENT_ORIGIN, fn: Prompt, props: PROMPT_PROPS, ...documented({ @@ -182,7 +187,7 @@ export const AGENT_REGISTRATIONS: readonly ComponentRegistration[] = [ }, { name: "ApproveAll", - origin: CORE_ORIGIN, + origin: AGENT_ORIGIN, fn: ApproveAll, props: NO_PROPS_SCHEMA, ...documented({ @@ -196,7 +201,7 @@ export const AGENT_REGISTRATIONS: readonly ComponentRegistration[] = [ }, { name: "AskPermission", - origin: CORE_ORIGIN, + origin: AGENT_ORIGIN, fn: AskPermission, props: NO_PROPS_SCHEMA, ...documented({ @@ -211,11 +216,11 @@ export const AGENT_REGISTRATIONS: readonly ComponentRegistration[] = [ ]; export function agentDocumentation( - read: DocumentationReader = packagedAssetReader, + read?: DocumentationReader, ): Operation { return packageDocumentation( new URL("./components.md", import.meta.url), - { owner: CORE_ORIGIN, asset: "packages/core/src/agent/components.md" }, + { owner: AGENT_ORIGIN, asset: "packages/agent/src/components.md" }, [ ...AGENT_REGISTRATIONS.map((registration) => registration.name), ...agentIdentityComponents().map((component) => component.name), diff --git a/packages/core/src/agent/configuration-record.ts b/packages/agent/src/configuration-record.ts similarity index 99% rename from packages/core/src/agent/configuration-record.ts rename to packages/agent/src/configuration-record.ts index 06123f294..cb000859b 100644 --- a/packages/core/src/agent/configuration-record.ts +++ b/packages/agent/src/configuration-record.ts @@ -27,7 +27,7 @@ import { Err, Ok } from "effection"; import type { Result } from "effection"; import type { SessionConfiguration } from "./agent-api.ts"; -import type { Json } from "../types.ts"; +import type { Json } from "@executablemd/core"; /** The member a record carries, and the only one this build writes. */ export const CONFIGURATION_MEMBER = "configuration"; diff --git a/packages/core/src/agent/conversation-provider.ts b/packages/agent/src/conversation-provider.ts similarity index 100% rename from packages/core/src/agent/conversation-provider.ts rename to packages/agent/src/conversation-provider.ts diff --git a/packages/core/src/agent/conversation.ts b/packages/agent/src/conversation.ts similarity index 97% rename from packages/core/src/agent/conversation.ts rename to packages/agent/src/conversation.ts index cb6ac2fdc..98ddf8a91 100644 --- a/packages/core/src/agent/conversation.ts +++ b/packages/agent/src/conversation.ts @@ -82,17 +82,26 @@ import type { Json as DurableJson, } from "@executablemd/durable-streams"; -import { executeInstalledWithApprovals } from "../execute.ts"; -import type { ExecutionApprovals, ExecutionInstallation, HostExecution } from "../execute.ts"; -import type { ApprovedElicitAnswer } from "../approved-generated-source.ts"; -import type { GeneratedXmdRequest, GeneratedXmdRootResult } from "../generated-xmd.ts"; -import { durabilityFailure } from "../errors.ts"; -import { isJsonObject, parseJson } from "../json.ts"; -import { retainedSource } from "../root-source.ts"; -import { encodedOffset, place } from "../secrets/secret-placement.ts"; -import type { ApprovedMatch } from "../secrets/secret-placement.ts"; -import type { SecretSpan } from "../secrets/scanner.ts"; +import { isJsonObject, parseJson, retainedSource } from "@executablemd/core"; +import type { ComponentInvocation, Json } from "@executablemd/core"; +import { + durabilityFailure, + executeInstalledWithApprovals, + placeApprovedCopies, +} from "@executablemd/core/host"; +import type { + ExecutionApprovals, + ExecutionInstallation, + HostExecution, + ApprovedElicitAnswer, + GeneratedXmdRequest, + GeneratedXmdRootResult, + ApprovedMatch, + SecretSpan, + IdentityClaimant, +} from "@executablemd/core/host"; import type { FeedbackSlice } from "./reply-review.ts"; +import { AGENT_ORIGIN } from "./origin.ts"; import { AgentConversationProvider } from "./conversation-provider.ts"; import type { AgentOptions, @@ -128,8 +137,6 @@ import type { import { openSessionRequest } from "./session-request.ts"; import type { SessionFacts } from "./session-request.ts"; import { sessionOf } from "./session-use.ts"; -import type { ComponentInvocation, IdentityClaimant } from "../invocation-identity.ts"; -import type { Json } from "../types.ts"; /** Why a host conversation cannot be opened, continued or inspected. */ export class AgentConversationError extends Error { @@ -716,7 +723,7 @@ function* serve( components: [ { name: CONVERSATION_COMPONENT, - origin: "@executablemd/core", + origin: AGENT_ORIGIN, props: { type: "object", properties: {}, additionalProperties: false }, description: "Hold one agent conversation open for the host that opened it.", factory: (claim) => @@ -1405,20 +1412,11 @@ function feedbackCopies( if (text.slice(slice.start, slice.end) !== rendered) { return []; } - const names = [...new Set(answer.copies.map(({ field }) => field))]; - const placements = place( - `${rendered}\n`, - names.map((name) => [name]), - 2, - ); - return answer.copies.flatMap(({ field, match }) => { - const placement = placements?.[names.indexOf(field)]; - const start = encodedOffset(placement, match.start); - const end = encodedOffset(placement, match.end); - return start === undefined || end === undefined || rendered.slice(start, end) !== match.bytes - ? [] - : [{ ...match, start: slice.start + start, end: slice.start + end }]; - }); + return placeApprovedCopies(rendered, answer.copies, 2).map((match) => ({ + ...match, + start: slice.start + match.start, + end: slice.start + match.end, + })); }); } diff --git a/packages/core/src/agent/errors.ts b/packages/agent/src/errors.ts similarity index 100% rename from packages/core/src/agent/errors.ts rename to packages/agent/src/errors.ts diff --git a/packages/core/src/agent/function-components.ts b/packages/agent/src/function-components.ts similarity index 98% rename from packages/core/src/agent/function-components.ts rename to packages/agent/src/function-components.ts index aeabca5e1..8d68a4b0d 100644 --- a/packages/core/src/agent/function-components.ts +++ b/packages/agent/src/function-components.ts @@ -1,5 +1,28 @@ -import { withInvocation, InvocationTeardownError } from "../invocation.ts"; -import { durabilityFailure, filesFatalFailure, firstCause } from "../errors.ts"; +import { + content, + getExpansion, + hasContent, + InvocationTeardownError, + raise, + scanSecrets, + secretPolicy, + withInvocation, +} from "@executablemd/core"; +import type { + ComponentInvocation, + FunctionComponent, + Json, + PropsSchema, + Expansion, +} from "@executablemd/core"; +import { + clearsLiveOutput, + durabilityFailure, + filesFatalFailure, + hasCause, + hasInvocationTeardown, +} from "@executablemd/core/host"; +import type { IdentityClaimant } from "@executablemd/core/host"; /** * The agent components (specs/acp-client-spec.md §Components). * @@ -18,16 +41,10 @@ import { durabilityFailure, filesFatalFailure, firstCause } from "../errors.ts"; import { scoped, spawn, suspend, withResolvers } from "effection"; import type { Operation, Task } from "effection"; -import { content, hasContent, raise } from "../component-api.ts"; -import { getExpansion } from "../expansion.ts"; import { openSessionRequest } from "./session-request.ts"; -import type { ComponentInvocation, FunctionComponent } from "../types.ts"; -import type { IdentityClaimant } from "../invocation-identity.ts"; import { cwd, flushOutput, parseDuration, reserveTerminal } from "@executablemd/runtime"; -import type { Json, PropsSchema } from "../types.ts"; -import type { Expansion } from "../expansion.ts"; import { Agent } from "./agent-api.ts"; import { sessionOf } from "./session-use.ts"; import type { @@ -74,7 +91,6 @@ import type { AgentPromptHandle, AgentPromptPublisher, } from "./publication.ts"; -import { clearsLiveOutput, secretPolicy, scanSecrets } from "../secrets/policy.ts"; import type { Stream, Subscription } from "effection"; import type { AgentPromptEvent } from "./agent-api.ts"; @@ -990,14 +1006,9 @@ export function* runPrompt( if (fatal !== undefined) { throw fatal; } - if ( - firstCause(error, (cause) => - cause instanceof InvocationTeardownError ? cause : undefined, - ) !== undefined - ) { + if (hasInvocationTeardown(error)) { const initiating = turnFailure ?? held?.failure; - throw initiating === undefined || - firstCause(error, (cause) => (cause === initiating ? initiating : undefined)) !== undefined + throw initiating === undefined || hasCause(error, initiating) ? error : new AggregateError([initiating, error], "agent prompt and release both failed", { cause: initiating, diff --git a/packages/core/src/agent/internal.ts b/packages/agent/src/internal.ts similarity index 98% rename from packages/core/src/agent/internal.ts rename to packages/agent/src/internal.ts index 650830b10..78f3337a9 100644 --- a/packages/core/src/agent/internal.ts +++ b/packages/agent/src/internal.ts @@ -14,7 +14,7 @@ import type { Operation } from "effection"; import type { PermissionMode, Session } from "./agent-api.ts"; import type { AgentPromptPublisher } from "./publication.ts"; import type { AgentPromptError } from "./errors.ts"; -import type { Expansion } from "../expansion.ts"; +import type { Expansion } from "@executablemd/core"; /** `path:line:column`, `line:column`, or `unknown` — the durable effect key. */ export function formatLocation(metadata: Expansion): string { diff --git a/packages/core/src/agent/journal.ts b/packages/agent/src/journal.ts similarity index 98% rename from packages/core/src/agent/journal.ts rename to packages/agent/src/journal.ts index 91fd13d31..2e4ba7b8a 100644 --- a/packages/core/src/agent/journal.ts +++ b/packages/agent/src/journal.ts @@ -47,8 +47,14 @@ */ import { createDurableOperation, ephemeral, serializeError } from "@executablemd/durable-streams"; -import type { AppendApprovals } from "../secrets/append-approval.ts"; -import type { ApprovedMatch } from "../secrets/secret-placement.ts"; +import type { SourcePosition } from "@executablemd/core"; +import { + durabilityFailure, + filesFatalFailure, + hasInvocationTeardown, + readSourceOwnerDescription, +} from "@executablemd/core/host"; +import type { AppendApprovals, ApprovedMatch } from "@executablemd/core/host"; import type { ActivateDurabilityFailure, DurableStream, @@ -60,8 +66,6 @@ import type { import { createContext, ensure, scoped } from "effection"; import type { Operation, Stream } from "effection"; import { Agent } from "./agent-api.ts"; -import { InvocationTeardownError } from "../invocation.ts"; -import { durabilityFailure, filesFatalFailure, firstCause } from "../errors.ts"; import type { AgentPromptEvent, PermissionOption, @@ -77,7 +81,6 @@ import type { SerializedPromptFailure } from "./errors.ts"; import { AgentInternal } from "./internal.ts"; import { HeldPromptInputRefusal, HostObservationFailure } from "./publication.ts"; import type { AgentPromptAssociation, AgentPromptHandle } from "./publication.ts"; -import { SourceOwner, sourceOwnerDescription } from "../source-owner.ts"; import { canonicalUsage, promptUsageDestination, @@ -85,7 +88,6 @@ import { serializePromptUsage, } from "./usage.ts"; import type { PromptUsage, PromptUsageDestination, PromptUsageReporter } from "./usage.ts"; -import type { SourcePosition } from "../types.ts"; /** The durable effect type every journaled Agent Prompt is recorded under. */ export const AGENT_PROMPT = "agent_prompt"; @@ -534,7 +536,7 @@ export function* persistPrompt( begun: () => AgentPromptHandle = () => undefined, feedback?: FeedbackApproval, ): Workflow { - const sourceOwner = yield* ephemeral(SourceOwner.get()); + const owned = yield* ephemeral(readSourceOwnerDescription(identity.position)); // Held here, and handed to nothing but the live runner below: the pending // description belongs to this function, so composition can settle the input // without reaching the journal, a second record or the retained history. @@ -542,7 +544,7 @@ export function* persistPrompt( type: AGENT_PROMPT, name: identity.name, input: identity.input, - ...sourceOwnerDescription(identity.position, sourceOwner), + ...owned, }; const stored = yield createDurableOperation( description, @@ -605,10 +607,7 @@ function promptPublication( throw error; } const fatal = durabilityFailure(error) ?? filesFatalFailure(error); - const teardown = firstCause(error, (cause) => - cause instanceof InvocationTeardownError ? cause : undefined, - ); - if (fatal !== undefined || teardown !== undefined) { + if (fatal !== undefined || hasInvocationTeardown(error)) { throw activateFailure(fatal ?? error); } if (error instanceof HostObservationFailure) { diff --git a/packages/core/src/agent/launch-coordinator.ts b/packages/agent/src/launch-coordinator.ts similarity index 100% rename from packages/core/src/agent/launch-coordinator.ts rename to packages/agent/src/launch-coordinator.ts diff --git a/packages/core/src/agent/launch-install.ts b/packages/agent/src/launch-install.ts similarity index 100% rename from packages/core/src/agent/launch-install.ts rename to packages/agent/src/launch-install.ts diff --git a/packages/core/src/agent/launch-journal.ts b/packages/agent/src/launch-journal.ts similarity index 99% rename from packages/core/src/agent/launch-journal.ts rename to packages/agent/src/launch-journal.ts index 322d476de..dc82d1082 100644 --- a/packages/core/src/agent/launch-journal.ts +++ b/packages/agent/src/launch-journal.ts @@ -43,8 +43,8 @@ import { readConfiguration, serializeConfiguration } from "./configuration-recor import { readCheckpoint } from "./checkpoint.ts"; import { persistPrompt } from "./journal.ts"; import type { PromptRecord } from "./journal.ts"; -import { sourceDescription } from "../source-position.ts"; -import type { SourcePosition } from "../types.ts"; +import { sourceDescription } from "@executablemd/core"; +import type { SourcePosition } from "@executablemd/core"; import type { PermissionMode } from "./agent-api.ts"; const AGENT_SESSION_LAUNCH = "agent_session_launch"; diff --git a/packages/core/src/agent/launch-owner.ts b/packages/agent/src/launch-owner.ts similarity index 99% rename from packages/core/src/agent/launch-owner.ts rename to packages/agent/src/launch-owner.ts index ae43e4d82..2c09ec24a 100644 --- a/packages/core/src/agent/launch-owner.ts +++ b/packages/agent/src/launch-owner.ts @@ -48,7 +48,7 @@ import { persistPreparation, } from "./launch-journal.ts"; import type { LaunchIdentity } from "./launch-journal.ts"; -import { getExpansion } from "../expansion.ts"; +import { getExpansion } from "@executablemd/core"; /** Where a launch's durable identity and normalized facts come from. */ export interface LaunchSite { diff --git a/packages/core/src/agent/launch-request.ts b/packages/agent/src/launch-request.ts similarity index 100% rename from packages/core/src/agent/launch-request.ts rename to packages/agent/src/launch-request.ts diff --git a/packages/core/src/agent/launch.ts b/packages/agent/src/launch.ts similarity index 100% rename from packages/core/src/agent/launch.ts rename to packages/agent/src/launch.ts diff --git a/packages/agent/src/origin.ts b/packages/agent/src/origin.ts new file mode 100644 index 000000000..1871d9495 --- /dev/null +++ b/packages/agent/src/origin.ts @@ -0,0 +1,11 @@ +/** + * The component origin every Agent registration, identity component and + * documentation contribution names. + * + * Still core's name. These components were core's before this package + * existed, and an origin is part of how a retained journal, canonical + * resolution and a documentation lookup identify a component, so moving the + * code does not move the name: authored documents and retained journals read + * the same under this package as they did under core. + */ +export const AGENT_ORIGIN = "@executablemd/core"; diff --git a/packages/core/src/agent/permission.ts b/packages/agent/src/permission.ts similarity index 100% rename from packages/core/src/agent/permission.ts rename to packages/agent/src/permission.ts diff --git a/packages/core/src/agent/provider-api.ts b/packages/agent/src/provider-api.ts similarity index 100% rename from packages/core/src/agent/provider-api.ts rename to packages/agent/src/provider-api.ts diff --git a/packages/core/src/agent/provider-configuration.ts b/packages/agent/src/provider-configuration.ts similarity index 98% rename from packages/core/src/agent/provider-configuration.ts rename to packages/agent/src/provider-configuration.ts index bbf5ca4dd..ce1d58b75 100644 --- a/packages/core/src/agent/provider-configuration.ts +++ b/packages/agent/src/provider-configuration.ts @@ -20,8 +20,8 @@ * admitted. */ -import type { Json, JsonObject } from "../types.ts"; -import { parseJson } from "../json.ts"; +import { parseJson } from "@executablemd/core"; +import type { Json, JsonObject } from "@executablemd/core"; import { Err, Ok } from "effection"; import type { Operation, Result } from "effection"; diff --git a/packages/core/src/agent/publication.ts b/packages/agent/src/publication.ts similarity index 100% rename from packages/core/src/agent/publication.ts rename to packages/agent/src/publication.ts diff --git a/packages/core/src/agent/reply-acceptance.ts b/packages/agent/src/reply-acceptance.ts similarity index 98% rename from packages/core/src/agent/reply-acceptance.ts rename to packages/agent/src/reply-acceptance.ts index 0a810d044..906d64c33 100644 --- a/packages/core/src/agent/reply-acceptance.ts +++ b/packages/agent/src/reply-acceptance.ts @@ -24,9 +24,9 @@ import { Err, Ok } from "effection"; import type { Operation, Result } from "effection"; import { createDurableOperation } from "@executablemd/durable-streams"; import type { DurableEvent, Json } from "@executablemd/durable-streams"; -import { isJsonObject } from "../json.ts"; +import { isJsonObject } from "@executablemd/core"; +import type { ApprovedMatch } from "@executablemd/core/host"; import { AGENT_PROMPT, parsePromptRecord } from "./journal.ts"; -import type { ApprovedMatch } from "../secrets/secret-placement.ts"; /** The durable effect an accepted reply is retained under. */ export const AGENT_PROMPT_REPLY = "agent_prompt_reply"; diff --git a/packages/core/src/agent/reply-review.ts b/packages/agent/src/reply-review.ts similarity index 97% rename from packages/core/src/agent/reply-review.ts rename to packages/agent/src/reply-review.ts index 31853d0ac..d95894c55 100644 --- a/packages/core/src/agent/reply-review.ts +++ b/packages/agent/src/reply-review.ts @@ -28,9 +28,8 @@ import type { Api } from "@effectionx/context-api"; import { ensure } from "effection"; import type { Operation } from "effection"; import type { AgentPromptHandle } from "./publication.ts"; -import type { SecretSpan } from "../secrets/scanner.ts"; -import type { SourceRange } from "../document-targets.ts"; -import type { ElicitChoiceSelection } from "../approved-generated-source.ts"; +import type { SourceRange } from "@executablemd/core"; +import type { SecretSpan, ElicitChoiceSelection } from "@executablemd/core/host"; /** Where feedback places an acknowledged answer from one question. */ export interface FeedbackSlice extends SourceRange { diff --git a/packages/core/src/agent/session-request.ts b/packages/agent/src/session-request.ts similarity index 100% rename from packages/core/src/agent/session-request.ts rename to packages/agent/src/session-request.ts diff --git a/packages/core/src/agent/session-setup.ts b/packages/agent/src/session-setup.ts similarity index 100% rename from packages/core/src/agent/session-setup.ts rename to packages/agent/src/session-setup.ts diff --git a/packages/core/src/agent/session-use.ts b/packages/agent/src/session-use.ts similarity index 100% rename from packages/core/src/agent/session-use.ts rename to packages/agent/src/session-use.ts diff --git a/packages/core/src/agent/usage.ts b/packages/agent/src/usage.ts similarity index 99% rename from packages/core/src/agent/usage.ts rename to packages/agent/src/usage.ts index 56beb82c9..99f65775d 100644 --- a/packages/core/src/agent/usage.ts +++ b/packages/agent/src/usage.ts @@ -17,7 +17,7 @@ import type { Json } from "@executablemd/durable-streams"; import type { Operation } from "effection"; -import { retainsOptionalText } from "../secrets/policy.ts"; +import { retainsOptionalText } from "@executablemd/core/host"; /** One build identity, where it was observed. */ export interface UsageBuild { diff --git a/packages/core/tests/agent-api.test.ts b/packages/agent/tests/agent-api.test.ts similarity index 73% rename from packages/core/tests/agent-api.test.ts rename to packages/agent/tests/agent-api.test.ts index 22188396e..f0d4f3f20 100644 --- a/packages/core/tests/agent-api.test.ts +++ b/packages/agent/tests/agent-api.test.ts @@ -13,13 +13,8 @@ import { describe, it } from "@executablemd/test-support/bdd"; import { expect } from "@executablemd/test-support/expect"; import { scoped } from "effection"; import type { Operation } from "effection"; -import { Agent } from "../src/agent/agent-api.ts"; -import type { - AgentOptions, - PermissionRequest, - Session, - SessionConfiguration, -} from "../src/agent/agent-api.ts"; +import { Agent } from "../api.ts"; +import type { AgentOptions, PermissionRequest, Session, SessionConfiguration } from "../api.ts"; function assertNoProviderError(error: unknown): void { expect(error).toBeInstanceOf(Error); @@ -197,3 +192,64 @@ describe("Tier AA — configuration and option discovery compose", () => { expect(seen).toEqual([["review"], []]); }); }); + +/** + * PA4 — the Agent Api a Plugin composes agent work through. + * + * A Plugin reaches agent work through `@executablemd/agent/api`, beside the + * generic Plugin surface on `@executablemd/core/api`, so what it can reach about + * a session is settled here: the Api itself, the choices an agent advertises, + * and the configuration a `` authored — all in the Agent package's own + * vocabulary. Whatever protocol the installed provider speaks does not appear. + * This suite imports the public entry rather than its module, so this + * exercises the name a Plugin actually imports. + */ +describe("PA4 — the Agent Api composes from the Plugin entrypoint", () => { + it("wraps options() and a configured session() the ordinary way", function* () { + const seen: unknown[][] = []; + const choices: AgentOptions = { + agent: "codex", + model: { + selected: "gpt-5.4", + options: [ + { + id: "gpt-5.4", + name: "GPT-5.4", + description: "the current one", + group: { id: "frontier", name: "Frontier" }, + }, + ], + }, + effort: null, + }; + + const composed = yield* scoped(function* (): Operation<[Session, AgentOptions]> { + yield* Agent.around( + { + // deno-lint-ignore require-yield + *session(args): Operation { + seen.push([...args]); + return { sessionKey: "plugin:review", cwd: "/repo" }; + }, + // deno-lint-ignore require-yield + *options(): Operation { + return choices; + }, + }, + { at: "min" }, + ); + yield* Agent.around({ + *session(args, next): Operation { + return yield* next(...args); + }, + }); + return [yield* Agent.operations.session("review"), yield* Agent.operations.options("codex")]; + }); + + // The request, and nothing else: no settings object travels this route. + expect(seen).toEqual([["review"]]); + expect(composed[0]).toEqual({ sessionKey: "plugin:review", cwd: "/repo" }); + expect(composed[1].model?.options[0]?.group).toEqual({ id: "frontier", name: "Frontier" }); + expect(composed[1].effort).toBe(null); + }); +}); diff --git a/packages/core/tests/agent-components.test.ts b/packages/agent/tests/agent-components.test.ts similarity index 97% rename from packages/core/tests/agent-components.test.ts rename to packages/agent/tests/agent-components.test.ts index 19939b669..b6a6eb06c 100644 --- a/packages/core/tests/agent-components.test.ts +++ b/packages/agent/tests/agent-components.test.ts @@ -16,17 +16,17 @@ import { ensureDir, rm, writeTextFile } from "@effectionx/fs"; import { randomUUID } from "node:crypto"; import * as path from "node:path"; import * as os from "node:os"; -import { executeInstalled } from "../host.ts"; -import { agentIdentityComponents } from "../src/agent/components.ts"; -import { execute } from "../src/execute.ts"; -import { Agent } from "../src/agent/agent-api.ts"; -import { sessionOf } from "../src/agent/session-use.ts"; -import type { AgentPromptEvent, PromptOptions, Session } from "../src/agent/agent-api.ts"; -import { AgentPromptError } from "../src/agent/errors.ts"; -import { readCompletedPrompts } from "../src/agent/journal.ts"; -import type { AgentProviderFactory } from "../src/agent/provider-api.ts"; -import { installAgentComponents } from "../src/agent/components.ts"; -import { Component } from "../src/component-api.ts"; +import { executeInstalled } from "@executablemd/core/host"; +import { agentIdentityComponents } from "../src/components.ts"; +import { execute } from "../../core/src/execute.ts"; +import { Agent } from "../src/agent-api.ts"; +import { sessionOf } from "../src/session-use.ts"; +import type { AgentPromptEvent, PromptOptions, Session } from "../src/agent-api.ts"; +import { AgentPromptError } from "../src/errors.ts"; +import { readCompletedPrompts } from "../src/journal.ts"; +import type { AgentProviderFactory } from "../src/provider-api.ts"; +import { installAgentComponents } from "../src/components.ts"; +import { Component } from "../../core/src/component-api.ts"; import type { Json } from "@executablemd/core"; interface StubResponse { diff --git a/packages/core/tests/agent-conversation.test.ts b/packages/agent/tests/agent-conversation.test.ts similarity index 98% rename from packages/core/tests/agent-conversation.test.ts rename to packages/agent/tests/agent-conversation.test.ts index dde16e362..ab2eeb6e7 100644 --- a/packages/core/tests/agent-conversation.test.ts +++ b/packages/agent/tests/agent-conversation.test.ts @@ -34,50 +34,51 @@ import type { Operation, Result, Stream } from "effection"; // The pinned factories are core-internal, as main keeps them: there is no // public siteless evaluator and no public pinning surface. -import { pinnedComponent, pinnedMutation } from "../src/generated-xmd.ts"; +import { pinnedComponent, pinnedMutation } from "../../core/src/generated-xmd.ts"; import type { GeneratedMutation, GeneratedObservation, GeneratedXmdRequest, -} from "../src/generated-xmd.ts"; +} from "../../core/src/generated-xmd.ts"; import { parsePromptRecord, useAgentConversation } from "../host.ts"; -import type { AgentConversation, ExecutionInstallation, GeneratedXmdRootResult } from "../host.ts"; -import type { InvocationForm } from "../src/invocation-identity.ts"; -import type { FunctionComponentDefinition } from "../src/types.ts"; -import { useSelection } from "./support/generated-selection.ts"; -import { answerProvider } from "./support/answer-provider.ts"; -import { contributeDocumentation, Documentation } from "../src/documentation-api.ts"; -import { registerComponents } from "../src/components/registration.ts"; -import { InvocationTeardownError } from "../src/invocation.ts"; -import { durabilityFailure, firstCause } from "../src/errors.ts"; -import { Execution } from "../src/execute.ts"; -import type { Json } from "../src/types.ts"; -import { Agent } from "../src/agent/agent-api.ts"; +import type { ExecutionInstallation, GeneratedXmdRootResult } from "@executablemd/core/host"; +import type { AgentConversation } from "../host.ts"; +import type { InvocationForm } from "../../core/src/invocation-identity.ts"; +import type { FunctionComponentDefinition } from "../../core/src/types.ts"; +import { useSelection } from "../../core/tests/support/generated-selection.ts"; +import { answerProvider } from "../../core/tests/support/answer-provider.ts"; +import { contributeDocumentation, Documentation } from "../../core/src/documentation-api.ts"; +import { registerComponents } from "../../core/src/components/registration.ts"; +import { InvocationTeardownError } from "../../core/src/invocation.ts"; +import { durabilityFailure, firstCause } from "../../core/src/errors.ts"; +import { Execution } from "../../core/src/execute.ts"; +import type { Json } from "../../core/src/types.ts"; +import { Agent } from "../src/agent-api.ts"; import type { AgentOptions, AgentPromptEvent, PromptOptions, Session, SessionConfiguration, -} from "../src/agent/agent-api.ts"; -import { installAgentComponents } from "../src/agent/components.ts"; -import { AgentConversationProvider } from "../src/agent/conversation-provider.ts"; -import type { AgentSessionRequest } from "../src/agent/session-request.ts"; -import type { AgentSessionSetup } from "../src/agent/session-setup.ts"; -import { sessionOf } from "../src/agent/session-use.ts"; -import { useAgentPromptPublisher } from "../src/agent/publication.ts"; -import { secretPolicy, useSecretScannerFactory } from "../src/secrets/policy.ts"; -import { createScannerWith } from "../src/secrets/scanner.ts"; -import type { SecretScanner } from "../src/secrets/scanner.ts"; -import { Elicitation } from "../src/elicitation-api.ts"; -import { getExpansion } from "../src/expansion.ts"; -import { elicitationEffectName, questionFingerprint } from "../src/elicit-journal.ts"; -import type { ElicitationRequest } from "../src/elicitation-api.ts"; +} from "../src/agent-api.ts"; +import { installAgentComponents } from "../src/components.ts"; +import { AgentConversationProvider } from "../src/conversation-provider.ts"; +import type { AgentSessionRequest } from "../src/session-request.ts"; +import type { AgentSessionSetup } from "../src/session-setup.ts"; +import { sessionOf } from "../src/session-use.ts"; +import { useAgentPromptPublisher } from "../src/publication.ts"; +import { secretPolicy, useSecretScannerFactory } from "../../core/src/secrets/policy.ts"; +import { createScannerWith } from "../../core/src/secrets/scanner.ts"; +import type { SecretScanner } from "../../core/src/secrets/scanner.ts"; +import { Elicitation } from "../../core/src/elicitation-api.ts"; +import { getExpansion } from "../../core/src/expansion.ts"; +import { elicitationEffectName, questionFingerprint } from "../../core/src/elicit-journal.ts"; +import type { ElicitationRequest } from "../../core/src/elicitation-api.ts"; import { acceptedReplies, AGENT_PROMPT_REPLY, useAgentReplyReview } from "../host.ts"; import type { AgentReplyDecision, AgentReplyHold } from "../host.ts"; -import type { SecretFinding } from "../src/secrets/findings.ts"; -import type { AgentLaunchCoordinator } from "../src/agent/launch-coordinator.ts"; -import type { ProviderSessionConfiguration } from "../src/agent/provider-configuration.ts"; +import type { SecretFinding } from "../../core/src/secrets/findings.ts"; +import type { AgentLaunchCoordinator } from "../src/launch-coordinator.ts"; +import type { ProviderSessionConfiguration } from "../src/provider-configuration.ts"; const AGENT = "stub-agent"; diff --git a/packages/core/tests/agent-function-components.test.ts b/packages/agent/tests/agent-function-components.test.ts similarity index 98% rename from packages/core/tests/agent-function-components.test.ts rename to packages/agent/tests/agent-function-components.test.ts index cfda8b192..b8e6e75ea 100644 --- a/packages/core/tests/agent-function-components.test.ts +++ b/packages/agent/tests/agent-function-components.test.ts @@ -18,12 +18,12 @@ import { ensureDir, rm, writeTextFile } from "@effectionx/fs"; import { randomUUID } from "node:crypto"; import * as path from "node:path"; import * as os from "node:os"; -import { execute } from "../src/execute.ts"; -import { useTempFileCompiler } from "../src/temp-file-compiler.ts"; -import { Agent } from "../src/agent/agent-api.ts"; -import { isSessionUse, sessionOf } from "../src/agent/session-use.ts"; -import { isSessionRequest } from "../src/agent/session-request.ts"; -import type { ConfigureAgentSession } from "../src/agent/session-setup.ts"; +import { execute } from "../../core/src/execute.ts"; +import { useTempFileCompiler } from "../../core/src/temp-file-compiler.ts"; +import { Agent } from "../src/agent-api.ts"; +import { isSessionUse, sessionOf } from "../src/session-use.ts"; +import { isSessionRequest } from "../src/session-request.ts"; +import type { ConfigureAgentSession } from "../src/session-setup.ts"; import type { AgentPromptEvent, PermissionOption, @@ -32,20 +32,21 @@ import type { PromptOptions, Session, SessionConfiguration, -} from "../src/agent/agent-api.ts"; -import { parsePromptFailure, AgentPromptError } from "../src/agent/errors.ts"; -import { executeInstalled, useAgentPromptPublisher } from "../host.ts"; -import { agentIdentityComponents } from "../src/agent/components.ts"; -import { installAgentComponents } from "../src/agent/components.ts"; -import { registerComponents } from "../src/components/registration.ts"; -import { AgentInternal } from "../src/agent/internal.ts"; -import { promptFailureFromRecord, parsePromptRecord } from "../src/agent/journal.ts"; -import { installApproveAll, installPromptFailurePolicy } from "../src/agent/permission.ts"; -import { inspectComponent } from "../src/inspect.ts"; -import type { AgentProviderFactory } from "../src/agent/provider-api.ts"; -import type { Json } from "../src/types.ts"; -import { useSecretScannerFactory } from "../src/secrets/policy.ts"; -import { createSecretScanner } from "../src/secrets/scanner.ts"; +} from "../src/agent-api.ts"; +import { parsePromptFailure, AgentPromptError } from "../src/errors.ts"; +import { executeInstalled } from "@executablemd/core/host"; +import { useAgentPromptPublisher } from "../host.ts"; +import { agentIdentityComponents } from "../src/components.ts"; +import { installAgentComponents } from "../src/components.ts"; +import { registerComponents } from "../../core/src/components/registration.ts"; +import { AgentInternal } from "../src/internal.ts"; +import { promptFailureFromRecord, parsePromptRecord } from "../src/journal.ts"; +import { installApproveAll, installPromptFailurePolicy } from "../src/permission.ts"; +import { inspectComponent } from "../../core/src/inspect.ts"; +import type { AgentProviderFactory } from "../src/provider-api.ts"; +import type { Json } from "../../core/src/types.ts"; +import { useSecretScannerFactory } from "../../core/src/secrets/policy.ts"; +import { createSecretScanner } from "../../core/src/secrets/scanner.ts"; /** What the stub agent was asked to do, in order. */ interface Trace { diff --git a/packages/core/tests/agent-session-launch.test.ts b/packages/agent/tests/agent-session-launch.test.ts similarity index 99% rename from packages/core/tests/agent-session-launch.test.ts rename to packages/agent/tests/agent-session-launch.test.ts index 76f978900..b18c5c82b 100644 --- a/packages/core/tests/agent-session-launch.test.ts +++ b/packages/agent/tests/agent-session-launch.test.ts @@ -19,13 +19,13 @@ import { ensureDir, rm, writeTextFile } from "@effectionx/fs"; import { createHash, randomUUID } from "node:crypto"; import * as path from "node:path"; import * as os from "node:os"; -import { execute } from "../src/execute.ts"; -import { executeInstalled } from "../host.ts"; -import { agentIdentityComponents } from "../src/agent/components.ts"; -import { Agent } from "../src/agent/agent-api.ts"; -import { sessionOf } from "../src/agent/session-use.ts"; -import { isSessionRequest } from "../src/agent/session-request.ts"; -import type { Session, SessionConfiguration, SessionLaunchResult } from "../src/agent/agent-api.ts"; +import { execute } from "../../core/src/execute.ts"; +import { executeInstalled } from "@executablemd/core/host"; +import { agentIdentityComponents } from "../src/components.ts"; +import { Agent } from "../src/agent-api.ts"; +import { sessionOf } from "../src/session-use.ts"; +import { isSessionRequest } from "../src/session-request.ts"; +import type { Session, SessionConfiguration, SessionLaunchResult } from "../src/agent-api.ts"; import type { ExecutableBuildBindingV1, ExitedLaunchRecord, @@ -33,12 +33,12 @@ import type { MaterializationPlan, MaterializedLaunchRecord, PreparedLaunchRecord, -} from "../src/agent/launch.ts"; -import { sameExecutableBuild } from "../src/agent/launch.ts"; -import { parseMaterialized, parsePrepared } from "../src/agent/launch-journal.ts"; -import type { AgentLaunchRequest } from "../src/agent/launch-request.ts"; -import { installAgentComponents } from "../src/agent/components.ts"; -import type { AgentProviderFactory } from "../src/agent/provider-api.ts"; +} from "../src/launch.ts"; +import { sameExecutableBuild } from "../src/launch.ts"; +import { parseMaterialized, parsePrepared } from "../src/launch-journal.ts"; +import type { AgentLaunchRequest } from "../src/launch-request.ts"; +import { installAgentComponents } from "../src/components.ts"; +import type { AgentProviderFactory } from "../src/provider-api.ts"; import { API, installControlledLauncher, @@ -48,7 +48,7 @@ import { useHostFiles, } from "@executablemd/runtime"; import type { NativeLaunchOutcome, NativeLaunchRequest } from "@executablemd/runtime"; -import type { Json } from "../src/types.ts"; +import type { Json } from "../../core/src/types.ts"; const ALPHABET = "abcdefghijklmnopqrstuvwxyz0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ"; @@ -1128,7 +1128,7 @@ describe("Tier FS — the final public launch surface", () => { it("FS8: core no longer publishes a launch journal to compose around", function* () { // The mechanism itself is gone, not hidden. A public phase journal is what // made the forgery durable, so its absence is part of the contract. - const core = yield* until(import("../mod.ts")); + const core = yield* until(import("@executablemd/core")); expect(Object.keys(core)).not.toContain("AgentLaunchJournal"); expect(Object.keys(core)).not.toContain("AgentLaunchJournalApi"); diff --git a/packages/core/tests/agent-session-setup.test.ts b/packages/agent/tests/agent-session-setup.test.ts similarity index 98% rename from packages/core/tests/agent-session-setup.test.ts rename to packages/agent/tests/agent-session-setup.test.ts index 45025efc0..327cdbe25 100644 --- a/packages/core/tests/agent-session-setup.test.ts +++ b/packages/agent/tests/agent-session-setup.test.ts @@ -16,13 +16,13 @@ import { describe, it } from "@executablemd/test-support/bdd"; import { expect } from "@executablemd/test-support/expect"; import { Err, Ok, sleep, spawn, withResolvers } from "effection"; import type { Operation, Result } from "effection"; -import type { Session, SessionConfiguration } from "../src/agent/agent-api.ts"; -import { createSessionSetupOwner } from "../src/agent/session-setup.ts"; -import type { AgentSessionSetup, SessionSetupOwner } from "../src/agent/session-setup.ts"; -import { configureSessionRequest, openSessionRequest } from "../src/agent/session-request.ts"; -import type { AgentSessionRequest } from "../src/agent/session-request.ts"; -import type { ProviderSessionConfiguration } from "../src/agent/provider-configuration.ts"; -import { configurationOf, isSessionUse, sessionOf } from "../src/agent/session-use.ts"; +import type { Session, SessionConfiguration } from "../src/agent-api.ts"; +import { createSessionSetupOwner } from "../src/session-setup.ts"; +import type { AgentSessionSetup, SessionSetupOwner } from "../src/session-setup.ts"; +import { configureSessionRequest, openSessionRequest } from "../src/session-request.ts"; +import type { AgentSessionRequest } from "../src/session-request.ts"; +import type { ProviderSessionConfiguration } from "../src/provider-configuration.ts"; +import { configurationOf, isSessionUse, sessionOf } from "../src/session-use.ts"; const SESSION: Session = { sessionKey: "stub:review", cwd: "/repo" }; diff --git a/packages/core/tests/agent-session-use-loaded-copy.test.ts b/packages/agent/tests/agent-session-use-loaded-copy.test.ts similarity index 97% rename from packages/core/tests/agent-session-use-loaded-copy.test.ts rename to packages/agent/tests/agent-session-use-loaded-copy.test.ts index 7f50693b6..d2031a423 100644 --- a/packages/core/tests/agent-session-use-loaded-copy.test.ts +++ b/packages/agent/tests/agent-session-use-loaded-copy.test.ts @@ -29,11 +29,11 @@ import { join } from "node:path"; import { tmpdir } from "node:os"; import process from "node:process"; import { fileURLToPath } from "node:url"; -import type { Session, SessionConfiguration } from "../src/agent/agent-api.ts"; -import { claimsConfiguration, configurationOf, isSessionUse } from "../src/agent/session-use.ts"; +import type { Session, SessionConfiguration } from "../src/agent-api.ts"; +import { claimsConfiguration, configurationOf, isSessionUse } from "../src/session-use.ts"; const REPOSITORY = fileURLToPath(new URL("../../..", import.meta.url)); -const SESSION_USE_MODULE = fileURLToPath(new URL("../src/agent/session-use.ts", import.meta.url)); +const SESSION_USE_MODULE = fileURLToPath(new URL("../src/session-use.ts", import.meta.url)); const SESSION: Session = { sessionKey: "xmd:v1:review", cwd: "/repo" }; diff --git a/packages/core/tests/agent-session-use.test.ts b/packages/agent/tests/agent-session-use.test.ts similarity index 98% rename from packages/core/tests/agent-session-use.test.ts rename to packages/agent/tests/agent-session-use.test.ts index 6435fd0bd..b88bff7f2 100644 --- a/packages/core/tests/agent-session-use.test.ts +++ b/packages/agent/tests/agent-session-use.test.ts @@ -14,7 +14,7 @@ */ import { describe, it } from "@executablemd/test-support/bdd"; import { expect } from "@executablemd/test-support/expect"; -import type { Session } from "../src/agent/agent-api.ts"; +import type { Session } from "../src/agent-api.ts"; import { AgentSessionUseError, claimsConfiguration, @@ -23,7 +23,7 @@ import { issueSessionUse, readSessionUse, sessionOf, -} from "../src/agent/session-use.ts"; +} from "../src/session-use.ts"; const SESSION: Session = { sessionKey: "xmd:v1:a", cwd: "/repo", agentSessionId: "agent-1" }; diff --git a/packages/core/tests/agent-stack.test.ts b/packages/agent/tests/agent-stack.test.ts similarity index 95% rename from packages/core/tests/agent-stack.test.ts rename to packages/agent/tests/agent-stack.test.ts index 83fa0757e..ffd2b307e 100644 --- a/packages/core/tests/agent-stack.test.ts +++ b/packages/agent/tests/agent-stack.test.ts @@ -15,19 +15,15 @@ import { ensureDir, rm, writeTextFile } from "@effectionx/fs"; import { randomUUID } from "node:crypto"; import * as path from "node:path"; import * as os from "node:os"; -import { execute } from "../src/execute.ts"; -import { registerComponents } from "../src/components/registration.ts"; -import { Agent } from "../src/agent/agent-api.ts"; -import type { PermissionOutcome, PermissionRequest } from "../src/agent/agent-api.ts"; -import { registerAgentProvider } from "../src/agent/provider-api.ts"; -import { useLaunchInstallation, useProviderInstallation } from "../src/agent/launch-install.ts"; -import type { AgentProviderFactory, AgentProviderOptions } from "../src/agent/provider-api.ts"; -import { - installApproveAll, - installApproveReads, - installAskPermission, -} from "../src/agent/permission.ts"; -import { installAgentComponents } from "../src/agent/components.ts"; +import { execute } from "../../core/src/execute.ts"; +import { registerComponents } from "../../core/src/components/registration.ts"; +import { Agent } from "../src/agent-api.ts"; +import type { PermissionOutcome, PermissionRequest } from "../src/agent-api.ts"; +import { registerAgentProvider } from "../src/provider-api.ts"; +import { useLaunchInstallation, useProviderInstallation } from "../src/launch-install.ts"; +import type { AgentProviderFactory, AgentProviderOptions } from "../src/provider-api.ts"; +import { installApproveAll, installApproveReads, installAskPermission } from "../src/permission.ts"; +import { installAgentComponents } from "../src/components.ts"; import type { Json } from "@executablemd/core"; /** A provider factory that records the options it is handed. */ diff --git a/packages/core/tests/agent-usage.test.ts b/packages/agent/tests/agent-usage.test.ts similarity index 94% rename from packages/core/tests/agent-usage.test.ts rename to packages/agent/tests/agent-usage.test.ts index 696e286cf..7195db337 100644 --- a/packages/core/tests/agent-usage.test.ts +++ b/packages/agent/tests/agent-usage.test.ts @@ -17,39 +17,36 @@ import { ensureDir, rm, writeTextFile } from "@effectionx/fs"; import { randomUUID } from "node:crypto"; import * as path from "node:path"; import * as os from "node:os"; -import { Agent } from "../src/agent/agent-api.ts"; -import type { AgentPromptEvent, PromptOptions, Session } from "../src/agent/agent-api.ts"; -import { executeInstalled, useAgentConversation } from "../host.ts"; -import type { ExecutionInstallation } from "../host.ts"; -import { agentIdentityComponents, installAgentComponents } from "../src/agent/components.ts"; -import { registerAgentProvider } from "../src/agent/provider-api.ts"; -import type { AgentProviderFactory } from "../src/agent/provider-api.ts"; -import type { AgentLaunchCoordinator } from "../src/agent/launch-coordinator.ts"; -import { AgentConversationProvider } from "../src/agent/conversation-provider.ts"; -import type { AgentSessionRequest } from "../src/agent/session-request.ts"; -import type { ProviderSessionConfiguration } from "../src/agent/session-setup.ts"; +import { Agent } from "../src/agent-api.ts"; +import type { AgentPromptEvent, PromptOptions, Session } from "../src/agent-api.ts"; +import { executeInstalled } from "@executablemd/core/host"; +import { useAgentConversation } from "../host.ts"; +import type { ExecutionInstallation } from "@executablemd/core/host"; +import { agentIdentityComponents, installAgentComponents } from "../src/components.ts"; +import { registerAgentProvider } from "../src/provider-api.ts"; +import type { AgentProviderFactory } from "../src/provider-api.ts"; +import type { AgentLaunchCoordinator } from "../src/launch-coordinator.ts"; +import { AgentConversationProvider } from "../src/conversation-provider.ts"; +import type { AgentSessionRequest } from "../src/session-request.ts"; +import type { ProviderSessionConfiguration } from "../src/session-setup.ts"; import { completedPromptUsage, observePermissionDecisions, parsePromptRecord, readCompletedPrompts, -} from "../src/agent/journal.ts"; -import { - promptUsageDestination, - readPromptUsage, - serializePromptUsage, -} from "../src/agent/usage.ts"; -import { createLaunchCoordinator } from "../src/agent/launch-coordinator.ts"; -import { registerComponents } from "../src/components/registration.ts"; -import type { SecretScanner } from "../src/secrets/scanner.ts"; -import type { SecretFinding } from "../src/secrets/findings.ts"; -import type { PromptUsage, PromptUsageReporter } from "../src/agent/usage.ts"; -import { useSecretDetection, useSecretScannerFactory } from "../src/secrets/policy.ts"; -import { attachInputOwner, createInputOwner } from "../src/secrets/inputs.ts"; +} from "../src/journal.ts"; +import { promptUsageDestination, readPromptUsage, serializePromptUsage } from "../src/usage.ts"; +import { createLaunchCoordinator } from "../src/launch-coordinator.ts"; +import { registerComponents } from "../../core/src/components/registration.ts"; +import type { SecretScanner } from "../../core/src/secrets/scanner.ts"; +import type { SecretFinding } from "../../core/src/secrets/findings.ts"; +import type { PromptUsage, PromptUsageReporter } from "../src/usage.ts"; +import { useSecretDetection, useSecretScannerFactory } from "../../core/src/secrets/policy.ts"; +import { attachInputOwner, createInputOwner } from "../../core/src/secrets/inputs.ts"; import { createContext } from "effection"; -import { retainablePromptUsage } from "../src/agent/usage.ts"; -import { createSecretScanner } from "../src/secrets/scanner.ts"; -import type { Json } from "../src/types.ts"; +import { retainablePromptUsage } from "../src/usage.ts"; +import { createSecretScanner } from "../../core/src/secrets/scanner.ts"; +import type { Json } from "../../core/src/types.ts"; const AGENT = "usage-agent"; diff --git a/packages/agent/tests/package-boundary.test.ts b/packages/agent/tests/package-boundary.test.ts new file mode 100644 index 000000000..0c4e074ca --- /dev/null +++ b/packages/agent/tests/package-boundary.test.ts @@ -0,0 +1,168 @@ +/** + * Tier PB — the boundary between Core and the Agent package. + * + * Core is the engine and the Agent package is one vocabulary over it, so the + * dependency runs one way. These rows hold that from what actually resolves + * rather than from what the source says: the names Core's namespaces export, + * its manifests, and what a Core-only execution can reach. The positive half is + * the same document run with the Agent package installed through its public + * entries, answered by an ordinary provider. The module-graph row, PB1, is in + * package-graph.test.ts, because it asks Deno's own resolver. + */ +import { describe, it } from "@executablemd/test-support/bdd"; +import { expect } from "@executablemd/test-support/expect"; +import { ensure, scoped, until } from "effection"; +import type { Operation, Result, Stream } from "effection"; +import { ensureDir, readTextFile, rm, writeTextFile } from "@effectionx/fs"; +import { randomUUID } from "node:crypto"; +import * as os from "node:os"; +import * as path from "node:path"; +import { fileURLToPath } from "node:url"; +import { InMemoryStream } from "@executablemd/durable-streams"; +import { execute } from "@executablemd/core"; +import type { DocumentExecution, Json } from "@executablemd/core"; +import { Agent } from "@executablemd/agent/api"; +import type { AgentPromptEvent, AgentProviderFactory } from "@executablemd/agent/api"; +import { agentIdentityComponents, installAgentComponents } from "@executablemd/agent/host"; +import { executeInstalled } from "@executablemd/core/host"; + +const REPOSITORY = fileURLToPath(new URL("../../../", import.meta.url)); + +function* manifest(relative: string): Operation> { + const parsed: unknown = JSON.parse(yield* readTextFile(path.join(REPOSITORY, relative))); + if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) { + throw new Error(`${relative} is not a JSON object`); + } + return Object.fromEntries(Object.entries(parsed)); +} + +function namesIn(section: unknown): string[] { + return typeof section === "object" && section !== null ? Object.keys(section) : []; +} + +/** A provider answering each prompt with its own text, bracketed. */ +const echo: AgentProviderFactory = function* (options) { + yield* Agent.around( + { + // deno-lint-ignore require-yield + *agent([name]) { + return name ?? options.defaultAgent; + }, + // deno-lint-ignore require-yield + *session([name]) { + return { sessionKey: `pb:${name ?? "default"}`, cwd: "/" }; + }, + // deno-lint-ignore require-yield + *prompt([content, promptOptions]): Operation> { + const text = `[${content}]`; + const events: AgentPromptEvent[] = [ + { + type: "started", + agent: promptOptions?.agent ?? options.defaultAgent, + session: { sessionKey: "pb:default", cwd: "/" }, + }, + { type: "text_delta", text }, + { type: "terminal", status: "completed" }, + ]; + return { + *[Symbol.iterator]() { + let index = 0; + return { + // deno-lint-ignore require-yield + *next() { + return index < events.length + ? { done: false as const, value: events[index++]! } + : { done: true as const, value: text }; + }, + }; + }, + }; + }, + }, + { at: "min" }, + ); +}; + +function* run( + doc: string, + start: (docPath: string) => Operation, +): Operation<{ output: string; result: Result }> { + const dir = path.join(os.tmpdir(), `xmd-pb-${randomUUID()}`); + yield* ensureDir(dir); + return yield* scoped(function* () { + yield* ensure(() => rm(dir, { recursive: true, force: true })); + const docPath = path.join(dir, "doc.md"); + yield* writeTextFile(docPath, doc); + const execution = yield* start(docPath); + const subscription = yield* execution.output; + let next = yield* subscription.next(); + while (!next.done) { + next = yield* subscription.next(); + } + return { output: next.value, result: yield* execution }; + }); +} + +const DOCUMENT = '\n\n\n'; + +describe("Tier PB — Core resolves no Agent package", () => { + it("PB2: Core's manifests declare no Agent dependency", function* () { + const deno = yield* manifest("packages/core/deno.json"); + const npm = yield* manifest("packages/core/package.json"); + for (const name of [ + ...namesIn(deno.imports), + ...namesIn(npm.dependencies), + ...namesIn(npm.peerDependencies), + ]) { + expect(name.startsWith("@executablemd/agent")).toBe(false); + } + const agent = yield* manifest("packages/agent/package.json"); + expect(namesIn(agent.dependencies)).toContain("@executablemd/core"); + }); + + it("PB3: Core's public namespaces export none of the Agent package's names", function* () { + const agentNames = new Set([ + ...Object.keys(yield* until(import("../api.ts"))), + ...Object.keys(yield* until(import("../host.ts"))), + ]); + expect(agentNames.size).toBeGreaterThan(0); + for (const entry of ["mod.ts", "api.ts", "host.ts"]) { + const core: object = yield* until(import(`../../core/${entry}`)); + expect([entry, Object.keys(core).filter((name) => agentNames.has(name))]).toEqual([ + entry, + [], + ]); + } + }); + + it("PB4: a Core-only execution cannot resolve the Agent vocabulary", function* () { + for (const [doc, name] of [ + [DOCUMENT, "Session"], + ['\n', "Prompt"], + ] as const) { + const { output, result } = yield* run(doc, (docPath) => + execute({ path: docPath, stream: new InMemoryStream() }), + ); + expect(output).not.toContain("[hello]"); + expect(!result.ok && result.error.message).toContain(`Cannot resolve component: ${name}`); + } + }); + + it("PB5: the Agent package installed over Core answers the same document", function* () { + const { output, result } = yield* run(DOCUMENT, function* (docPath) { + yield* installAgentComponents({ + rootProvider: { + factory: echo, + options: { defaultAgent: "pb", permissionMode: "deny-all" }, + }, + }); + return yield* executeInstalled({ path: docPath, stream: new InMemoryStream() }, [ + { components: agentIdentityComponents() }, + ]); + }); + if (!result.ok) { + throw result.error; + } + expect(output).toContain("[hello]"); + }); +}); diff --git a/packages/agent/tests/package-graph.test.ts b/packages/agent/tests/package-graph.test.ts new file mode 100644 index 000000000..a73aff92f --- /dev/null +++ b/packages/agent/tests/package-graph.test.ts @@ -0,0 +1,79 @@ +/** + * Tier PB, PB1 — no public Core entry's resolved module graph reaches the Agent + * package. + * + * Asked of Deno's resolver through `deno info --json`, so a graph error fails + * the row rather than hiding an edge. Deno-only for that reason; the rest of + * Tier PB is runtime-neutral and lives in package-boundary.test.ts. + */ +import { describe, it } from "@executablemd/test-support/bdd"; +import { expect } from "@executablemd/test-support/expect"; +import type { Operation } from "effection"; +import { exec } from "@effectionx/process"; +import * as path from "node:path"; +import process from "node:process"; +import { fileURLToPath, pathToFileURL } from "node:url"; + +const REPOSITORY = fileURLToPath(new URL("../../../", import.meta.url)); +const AGENT_PACKAGE = pathToFileURL(path.join(REPOSITORY, "packages/agent/")).href; +const OLD_AGENT_SOURCE = pathToFileURL(path.join(REPOSITORY, "packages/core/src/agent/")).href; + +/** Every public Core entry, by manifest subpath. */ +const CORE_ENTRIES = [ + "mod.ts", + "api.ts", + "host.ts", + "component-modules/deno.ts", + "component-modules/node.ts", + "component-modules/bun.ts", +]; + +/** The modules one entry's resolved graph contains, failing on any graph error. */ +function* graphOf(entry: string): Operation { + const info = yield* exec(process.execPath, { + arguments: ["info", "--json", "--frozen", "--node-modules-dir=none", entry], + cwd: REPOSITORY, + }).join(); + if (info.code !== 0) { + throw new Error(`deno info failed for ${entry}:\n${info.stderr}`); + } + const parsed: unknown = JSON.parse(info.stdout); + const modules = + typeof parsed === "object" && parsed !== null ? Reflect.get(parsed, "modules") : undefined; + if (!Array.isArray(modules) || modules.length === 0) { + throw new Error(`deno info reported no modules for ${entry}`); + } + const specifiers: string[] = []; + for (const module of modules) { + const specifier: unknown = Reflect.get(module, "specifier"); + const error: unknown = Reflect.get(module, "error"); + if (error !== undefined) { + throw new Error(`${entry} has a graph error at ${String(specifier)}: ${String(error)}`); + } + if (typeof specifier === "string") { + specifiers.push(specifier); + } + } + return specifiers; +} + +function agentModules(specifiers: readonly string[]): string[] { + return specifiers.filter( + (specifier) => specifier.startsWith(AGENT_PACKAGE) || specifier.startsWith(OLD_AGENT_SOURCE), + ); +} + +describe("Tier PB — Core resolves no Agent package", () => { + it("PB1: no public Core entry's module graph reaches the Agent package", function* () { + for (const entry of CORE_ENTRIES) { + const modules = yield* graphOf(path.join("packages/core", entry)); + expect([entry, agentModules(modules)]).toEqual([entry, []]); + } + // The positive control: the same probe sees the Agent package, and Core + // beneath it, where they are actually in the graph. + const agent = yield* graphOf("packages/agent/host.ts"); + expect(agentModules(agent)).toContain(`${AGENT_PACKAGE}src/components.ts`); + expect(agent).toContain(pathToFileURL(path.join(REPOSITORY, "packages/core/mod.ts")).href); + expect(agentModules(agent).some((one) => one.startsWith(OLD_AGENT_SOURCE))).toBe(false); + }); +}); diff --git a/packages/core/tests/root-provider.test.ts b/packages/agent/tests/root-provider.test.ts similarity index 96% rename from packages/core/tests/root-provider.test.ts rename to packages/agent/tests/root-provider.test.ts index a433bd0b4..43c21991b 100644 --- a/packages/core/tests/root-provider.test.ts +++ b/packages/agent/tests/root-provider.test.ts @@ -16,22 +16,22 @@ import { ensureDir, rm, writeTextFile } from "@effectionx/fs"; import { randomUUID } from "node:crypto"; import * as path from "node:path"; import * as os from "node:os"; -import { execute } from "../src/execute.ts"; -import { Agent } from "../src/agent/agent-api.ts"; -import { sessionOf } from "../src/agent/session-use.ts"; -import type { AgentPromptEvent, PromptOptions, Session } from "../src/agent/agent-api.ts"; -import { AgentPromptError } from "../src/agent/errors.ts"; +import { execute } from "../../core/src/execute.ts"; +import { Agent } from "../src/agent-api.ts"; +import { sessionOf } from "../src/session-use.ts"; +import type { AgentPromptEvent, PromptOptions, Session } from "../src/agent-api.ts"; +import { AgentPromptError } from "../src/errors.ts"; import { AgentProviderInstallError, installAgentProvider, registerAgentProvider, -} from "../src/agent/provider-api.ts"; -import type { AgentProviderFactory, AgentProviderOptions } from "../src/agent/provider-api.ts"; -import type { AgentLaunchCoordinator } from "../src/agent/launch-coordinator.ts"; -import type { AgentSessionSetup } from "../src/agent/session-setup.ts"; -import type { ProviderSessionConfiguration } from "../src/agent/provider-configuration.ts"; -import { openSessionRequest } from "../src/agent/session-request.ts"; -import { installAgentComponents } from "../src/agent/components.ts"; +} from "../src/provider-api.ts"; +import type { AgentProviderFactory, AgentProviderOptions } from "../src/provider-api.ts"; +import type { AgentLaunchCoordinator } from "../src/launch-coordinator.ts"; +import type { AgentSessionSetup } from "../src/session-setup.ts"; +import type { ProviderSessionConfiguration } from "../src/provider-configuration.ts"; +import { openSessionRequest } from "../src/session-request.ts"; +import { installAgentComponents } from "../src/components.ts"; import type { Json } from "@executablemd/core"; interface ProviderState { diff --git a/packages/cli/package.json b/packages/cli/package.json index 7cfc98353..17c7280dc 100644 --- a/packages/cli/package.json +++ b/packages/cli/package.json @@ -17,6 +17,7 @@ "@agentclientprotocol/sdk": "1.3.0", "@effectionx/stream-helpers": "0.8.3", "@executablemd/acp": "workspace:*", + "@executablemd/agent": "workspace:*", "@executablemd/core": "workspace:*", "@executablemd/durable-streams": "workspace:*", "@executablemd/git": "workspace:*", diff --git a/packages/cli/src/agent-config.ts b/packages/cli/src/agent-config.ts index 8552d0b80..ad7fc3b31 100644 --- a/packages/cli/src/agent-config.ts +++ b/packages/cli/src/agent-config.ts @@ -8,7 +8,7 @@ * mapping can be asserted on its own. */ -import type { PermissionMode } from "@executablemd/core"; +import type { PermissionMode } from "@executablemd/agent/api"; /** What settling who writes needs, and the whole of it. */ export interface AuthorshipFlags { diff --git a/packages/cli/src/agent-options.ts b/packages/cli/src/agent-options.ts index f40fc80ae..802e41ba7 100644 --- a/packages/cli/src/agent-options.ts +++ b/packages/cli/src/agent-options.ts @@ -15,7 +15,7 @@ * wrong. */ -import type { AgentOptions, AgentOptionSet } from "@executablemd/core"; +import type { AgentOptions, AgentOptionSet } from "@executablemd/agent/api"; /** The one action this command takes, and the options it accepts. */ export const AGENT_ACTION = "options"; diff --git a/packages/cli/src/agent-stack.ts b/packages/cli/src/agent-stack.ts index 11f735a49..e542e684c 100644 --- a/packages/cli/src/agent-stack.ts +++ b/packages/cli/src/agent-stack.ts @@ -15,12 +15,9 @@ * session assembly enter. */ -import { - installAgentComponents, - installPermissionMode, - registerAgentProvider, -} from "@executablemd/core"; -import type { AgentProviderFactory, PermissionMode } from "@executablemd/core"; +import { registerAgentProvider } from "@executablemd/agent/api"; +import { installAgentComponents, installPermissionMode } from "@executablemd/agent/host"; +import type { AgentProviderFactory, PermissionMode } from "@executablemd/agent/api"; import { installForegroundLauncher, env as readEnv } from "@executablemd/runtime"; import { createAcpxProvider, createAcpxSessionStore, DEFAULT_AGENT_NAME } from "@executablemd/acp"; import type { AcpxProviderDependencies } from "@executablemd/acp"; diff --git a/packages/cli/src/cli.ts b/packages/cli/src/cli.ts index d5187bded..df776ee37 100755 --- a/packages/cli/src/cli.ts +++ b/packages/cli/src/cli.ts @@ -65,8 +65,6 @@ import process from "node:process"; import { program, object, field, cli, commands } from "configliere"; import { z } from "zod"; import { - Agent, - AgentProviders, Config, asDocumentTargetError, execute, @@ -74,13 +72,13 @@ import { formatDocumentReference, inlineSource, inspectDocument, - agentIdentityComponents, - installAgentComponents, retainedSource, rootSourcePath, useNormalizedOutput, useTerminalOutput, } from "@executablemd/core"; +import { Agent, AgentProviders } from "@executablemd/agent/api"; +import { agentIdentityComponents, installAgentComponents } from "@executablemd/agent/host"; import { executeInstalled } from "@executablemd/core/host"; import type { ExecutionInstallation, MarkdownComponent } from "@executablemd/core/host"; import type { diff --git a/packages/cli/src/diagnostic-agent.ts b/packages/cli/src/diagnostic-agent.ts index bc62fd30f..43e59533b 100644 --- a/packages/cli/src/diagnostic-agent.ts +++ b/packages/cli/src/diagnostic-agent.ts @@ -1,7 +1,7 @@ import { createAcpxProvider } from "@executablemd/acp"; import type { AcpxProviderDependencies } from "@executablemd/acp"; import type { EmbeddedAdapters } from "@executablemd/acp/embedded-adapters"; -import type { AgentProviderFactory } from "@executablemd/core"; +import type { AgentProviderFactory } from "@executablemd/agent/api"; import { scoped } from "effection"; import { cwd, exec, platform, realpath, useQuietProcessOutput } from "@executablemd/runtime"; diff --git a/packages/cli/src/headless/host.ts b/packages/cli/src/headless/host.ts index 62a7327d9..1978bc4b6 100644 --- a/packages/cli/src/headless/host.ts +++ b/packages/cli/src/headless/host.ts @@ -2,8 +2,10 @@ import { childRuntime } from "./runtime.ts"; import { ensure, Err, Ok, scoped, suspend, useScope, withResolvers } from "effection"; import type { Operation, Result, Task } from "effection"; import { ensureDir } from "@effectionx/fs"; -import { Agent, content, hasContent } from "@executablemd/core"; -import type { AgentProviderFactory, Json } from "@executablemd/core"; +import { content, hasContent } from "@executablemd/core"; +import { Agent } from "@executablemd/agent/api"; +import type { Json } from "@executablemd/core"; +import type { AgentProviderFactory } from "@executablemd/agent/api"; import { createDurableOperation } from "@executablemd/durable-streams"; import { createAcpRuntime, diff --git a/packages/cli/src/plan-component.ts b/packages/cli/src/plan-component.ts index d0cb1e150..48b3be0da 100644 --- a/packages/cli/src/plan-component.ts +++ b/packages/cli/src/plan-component.ts @@ -51,7 +51,6 @@ import type { Operation, Result, Scope } from "effection"; import { createDurableOperation, StaleInputError } from "@executablemd/durable-streams"; import type { Json } from "@executablemd/durable-streams"; import { - agentIdentityComponents, content, DocumentOutput, retainedSource, @@ -61,6 +60,7 @@ import { tryContent, validateDocumentStructure, } from "@executablemd/core"; +import { agentIdentityComponents } from "@executablemd/agent/host"; import { classifyPlanResponse, generatedRequestRefusal, diff --git a/packages/cli/src/plan-writer-profile.ts b/packages/cli/src/plan-writer-profile.ts index 03cfa6eaa..b4b614f88 100644 --- a/packages/cli/src/plan-writer-profile.ts +++ b/packages/cli/src/plan-writer-profile.ts @@ -34,19 +34,19 @@ import { mkdir, readdir, rmdir } from "node:fs/promises"; import { homedir } from "node:os"; import { join } from "node:path"; +import { retainedSource, useNormalizedOutput, useTerminalOutput } from "@executablemd/core"; +import { registerAgentProvider } from "@executablemd/agent/api"; import { agentIdentityComponents, installAgentComponents, installPermissionMode, installPromptFailurePolicy, - registerAgentProvider, - retainedSource, - useNormalizedOutput, - useTerminalOutput, -} from "@executablemd/core"; -import type { AgentProviderOptions, Json } from "@executablemd/core"; +} from "@executablemd/agent/host"; +import type { Json } from "@executablemd/core"; +import type { AgentProviderOptions } from "@executablemd/agent/api"; import type { MarkdownComponent } from "@executablemd/core/host"; -import { executeInstalled, installInvocationAgentProvider } from "@executablemd/core/host"; +import { executeInstalled } from "@executablemd/core/host"; +import { installInvocationAgentProvider } from "@executablemd/agent/host"; import { createAcpxProvider } from "@executablemd/acp"; import type { AcpxProviderDependencies } from "@executablemd/acp"; import type { DurableStream } from "@executablemd/durable-streams"; diff --git a/packages/cli/src/repl-profile.ts b/packages/cli/src/repl-profile.ts index bbf35c559..331ac0f89 100644 --- a/packages/cli/src/repl-profile.ts +++ b/packages/cli/src/repl-profile.ts @@ -16,8 +16,9 @@ import { replTesting } from "./repl/sidekick/testing.ts"; import type { ReplTesting } from "./repl/sidekick/testing.ts"; import type { AcpxProviderDependencies } from "@executablemd/acp"; -import { agentIdentityComponents } from "@executablemd/core"; -import type { PermissionMode, SyntaxSymbols } from "@executablemd/core"; +import { agentIdentityComponents } from "@executablemd/agent/host"; +import type { SyntaxSymbols } from "@executablemd/core"; +import type { PermissionMode } from "@executablemd/agent/api"; import type { GeneratedSelection } from "@executablemd/core/api"; import type { ExecutionInstallation } from "@executablemd/core/host"; import { scoped, useScope } from "effection"; diff --git a/packages/cli/src/repl/agent.ts b/packages/cli/src/repl/agent.ts index 04c67b6e2..f2757146a 100644 --- a/packages/cli/src/repl/agent.ts +++ b/packages/cli/src/repl/agent.ts @@ -57,21 +57,21 @@ import { action, createSignal, ensure, resource, useScope } from "effection"; import type { Operation, Scope, Stream } from "effection"; -import { Agent, denyPermission } from "@executablemd/core"; +import { Agent, denyPermission } from "@executablemd/agent/api"; import type { AgentPromptEvent, PermissionMode, PermissionOption, PermissionOutcome, PermissionRequest, -} from "@executablemd/core"; -import { useAgentPromptPublisher } from "@executablemd/core/host"; +} from "@executablemd/agent/api"; +import { useAgentPromptPublisher } from "@executablemd/agent/host"; +import type { ExecutionInstallation } from "@executablemd/core/host"; import type { AgentPromptHandle, AgentPromptPublication, AgentPromptPublisher, - ExecutionInstallation, -} from "@executablemd/core/host"; +} from "@executablemd/agent/host"; import type { ReplWaits } from "./lifecycle.ts"; import { DurableContext } from "@executablemd/durable-streams"; import type { DurableEvent } from "@executablemd/durable-streams"; diff --git a/packages/cli/src/repl/application.ts b/packages/cli/src/repl/application.ts index 0ebf9ecbd..9852666fa 100644 --- a/packages/cli/src/repl/application.ts +++ b/packages/cli/src/repl/application.ts @@ -20,7 +20,7 @@ import type { ReplCaret } from "./caret.ts"; import type { MessageOrigin } from "./sidekick/history.ts"; import { Ok, type Result } from "effection"; import type { Json } from "@executablemd/durable-streams"; -import type { AgentOption, AgentOptions, SessionConfiguration } from "@executablemd/core"; +import type { AgentOption, AgentOptions, SessionConfiguration } from "@executablemd/agent/api"; import { describe as describeNode, diff --git a/packages/cli/src/repl/model.ts b/packages/cli/src/repl/model.ts index fd7f69098..88446eb71 100644 --- a/packages/cli/src/repl/model.ts +++ b/packages/cli/src/repl/model.ts @@ -40,8 +40,9 @@ import type { EntryPlacement } from "./entry-placement.ts"; import { Err, Ok } from "effection"; import type { Result } from "effection"; import { validateBindingName } from "@executablemd/core"; -import { AGENT_PROMPT, parsePromptRecord, readElicitationSchema } from "@executablemd/core/host"; -import type { PromptRecord } from "@executablemd/core/host"; +import { readElicitationSchema } from "@executablemd/core/host"; +import { AGENT_PROMPT, parsePromptRecord } from "@executablemd/agent/host"; +import type { PromptRecord } from "@executablemd/agent/host"; import { projectUsage, type ReplUsage } from "./usage.ts"; import type { Close, DurableEvent, Json, Yield } from "@executablemd/durable-streams"; diff --git a/packages/cli/src/repl/program.ts b/packages/cli/src/repl/program.ts index 5191d4a91..7dcab134c 100644 --- a/packages/cli/src/repl/program.ts +++ b/packages/cli/src/repl/program.ts @@ -129,7 +129,8 @@ import { withoutAbsentEntry, withoutLiveDrawers, } from "./application.ts"; -import type { AgentOptions, Json, NormalizedIssue, SessionConfiguration } from "@executablemd/core"; +import type { Json, NormalizedIssue } from "@executablemd/core"; +import type { AgentOptions, SessionConfiguration } from "@executablemd/agent/api"; import { previewGeneratedXmdRoot } from "@executablemd/core/host"; import type { ReplQuestion } from "./elicitation.ts"; import type { diff --git a/packages/cli/src/repl/session.ts b/packages/cli/src/repl/session.ts index 0375d6805..9db6ffd63 100644 --- a/packages/cli/src/repl/session.ts +++ b/packages/cli/src/repl/session.ts @@ -81,7 +81,8 @@ import { } from "effection"; import type { Operation, Result, Stream, Task } from "effection"; import { Component, INLINE_SOURCE_PATH, inlineSource, validateDocument } from "@executablemd/core"; -import type { DocumentValidationDiagnostic, Json, PermissionMode } from "@executablemd/core"; +import type { DocumentValidationDiagnostic, Json } from "@executablemd/core"; +import type { PermissionMode } from "@executablemd/agent/api"; import type { GeneratedSelection } from "@executablemd/core/api"; import { API, Permissions } from "@executablemd/runtime"; import { Stdio } from "@effectionx/process"; diff --git a/packages/cli/src/repl/sidekick/assembly.ts b/packages/cli/src/repl/sidekick/assembly.ts index 196ac8ee0..1313eb5ce 100644 --- a/packages/cli/src/repl/sidekick/assembly.ts +++ b/packages/cli/src/repl/sidekick/assembly.ts @@ -25,9 +25,9 @@ import type { ReplPluginExtension } from "../../repl-api.ts"; * a raw programmatic session gets. */ -import { installAgentComponents } from "@executablemd/core"; +import { installAgentComponents } from "@executablemd/agent/host"; import type { ExecutionInstallation } from "@executablemd/core/host"; -import type { PermissionMode } from "@executablemd/core"; +import type { PermissionMode } from "@executablemd/agent/api"; import type { Operation } from "effection"; import { createAcpxProvider } from "@executablemd/acp"; import type { AcpxProviderDependencies } from "@executablemd/acp"; diff --git a/packages/cli/src/repl/sidekick/asset-image.ts b/packages/cli/src/repl/sidekick/asset-image.ts index 47ac3c6ae..1f2eaed50 100644 --- a/packages/cli/src/repl/sidekick/asset-image.ts +++ b/packages/cli/src/repl/sidekick/asset-image.ts @@ -1,4 +1,4 @@ -import type { PromptImage } from "@executablemd/core/api"; +import type { PromptImage } from "@executablemd/agent/api"; import { Buffer } from "node:buffer"; import { createHash } from "node:crypto"; import type { Operation } from "effection"; diff --git a/packages/cli/src/repl/sidekick/feedback.ts b/packages/cli/src/repl/sidekick/feedback.ts index 60c1f73b5..d2ff4b09d 100644 --- a/packages/cli/src/repl/sidekick/feedback.ts +++ b/packages/cli/src/repl/sidekick/feedback.ts @@ -35,7 +35,7 @@ import { Err, Ok } from "effection"; import type { Operation, Result } from "effection"; -import type { FeedbackSlice } from "@executablemd/core/host"; +import type { FeedbackSlice } from "@executablemd/agent/host"; import { DESIGNATED, DRAFT_FILLED, renderRead, renderReceipt } from "./controls.ts"; import { acknowledgedControlOutcomes, controlSlot } from "./control-outcomes.ts"; diff --git a/packages/cli/src/repl/sidekick/model.ts b/packages/cli/src/repl/sidekick/model.ts index 5532694b6..36ddbae5a 100644 --- a/packages/cli/src/repl/sidekick/model.ts +++ b/packages/cli/src/repl/sidekick/model.ts @@ -37,15 +37,15 @@ import type { HumanStopFact, RecoveryDisposition } from "./recovery-state.ts"; import type { MessageOrigin } from "./history.ts"; import { Err, Ok } from "effection"; import type { Result } from "effection"; +import { previewGeneratedXmdRoot } from "@executablemd/core/host"; import { acceptedReplies, AGENT_PROMPT, AGENT_PROMPT_REPLY, parsePromptRecord, - previewGeneratedXmdRoot, -} from "@executablemd/core/host"; -import type { SessionConfiguration } from "@executablemd/core"; -import type { PromptRecord } from "@executablemd/core/host"; +} from "@executablemd/agent/host"; +import type { SessionConfiguration } from "@executablemd/agent/api"; +import type { PromptRecord } from "@executablemd/agent/host"; import { projectUsage, type ReplUsage } from "../usage.ts"; import { parseDurableEvent } from "@executablemd/durable-streams"; import type { DurableEvent } from "@executablemd/durable-streams"; diff --git a/packages/cli/src/repl/sidekick/owner.ts b/packages/cli/src/repl/sidekick/owner.ts index d5d75b48f..b32853fe0 100644 --- a/packages/cli/src/repl/sidekick/owner.ts +++ b/packages/cli/src/repl/sidekick/owner.ts @@ -105,16 +105,16 @@ import { withResolvers, } from "effection"; import type { Operation, Result, Stream, Task } from "effection"; +import { GeneratedXmdRootError, previewGeneratedXmdRoot } from "@executablemd/core/host"; import { acceptedReplies, AGENT_PROMPT, AgentReplyWithheldError, - GeneratedXmdRootError, parsePromptRecord, - previewGeneratedXmdRoot, useAgentPromptPublisher, useAgentReplyReview, -} from "@executablemd/core/host"; +} from "@executablemd/agent/host"; +import type { ExecutionInstallation, GeneratedXmdRootResult } from "@executablemd/core/host"; import type { AgentPromptHandle, AgentPromptPublisher, @@ -122,19 +122,17 @@ import type { AgentReplyFinding, AgentReplyHold, FeedbackSlice, - ExecutionInstallation, - GeneratedXmdRootResult, -} from "@executablemd/core/host"; +} from "@executablemd/agent/host"; import type { DurableEvent } from "@executablemd/durable-streams"; import { serializeError } from "@executablemd/durable-streams"; -import { useAgentConversation } from "@executablemd/core/host"; -import type { AgentConversation } from "@executablemd/core/host"; +import { useAgentConversation } from "@executablemd/agent/host"; +import type { AgentConversation } from "@executablemd/agent/host"; import type { AgentOptions, AgentOptionsRequest, PromptImage, SessionConfiguration, -} from "@executablemd/core"; +} from "@executablemd/agent/api"; import { parseDurableEvent } from "@executablemd/durable-streams"; import { ReplHost } from "../host.ts"; diff --git a/packages/cli/src/repl/sidekick/questions.ts b/packages/cli/src/repl/sidekick/questions.ts index 3368c19cf..b647a8787 100644 --- a/packages/cli/src/repl/sidekick/questions.ts +++ b/packages/cli/src/repl/sidekick/questions.ts @@ -4,7 +4,7 @@ import { questionFingerprint, retainsOptionalText, } from "@executablemd/core/host"; -import type { AgentReplyHold } from "@executablemd/core/host"; +import type { AgentReplyHold } from "@executablemd/agent/host"; /** * The Sidekick's own questions, and how one reaches the response that asked it. * diff --git a/packages/cli/src/repl/sidekick/recovery-owner.ts b/packages/cli/src/repl/sidekick/recovery-owner.ts index abbeb1086..7a07340b5 100644 --- a/packages/cli/src/repl/sidekick/recovery-owner.ts +++ b/packages/cli/src/repl/sidekick/recovery-owner.ts @@ -1,5 +1,5 @@ import { z } from "zod"; -import { AGENT_PROMPT, parsePromptRecord } from "@executablemd/core/host"; +import { AGENT_PROMPT, parsePromptRecord } from "@executablemd/agent/host"; import { parseDurableEvent } from "@executablemd/durable-streams"; import { agentSessionKeyDigest } from "@executablemd/runtime"; import { Err, Ok } from "effection"; diff --git a/packages/cli/src/repl/sidekick/recovery-state.ts b/packages/cli/src/repl/sidekick/recovery-state.ts index fb8dca023..904e9f591 100644 --- a/packages/cli/src/repl/sidekick/recovery-state.ts +++ b/packages/cli/src/repl/sidekick/recovery-state.ts @@ -1,6 +1,6 @@ import { Err, Ok } from "effection"; import type { Result } from "effection"; -import { AGENT_PROMPT, parsePromptRecord } from "@executablemd/core/host"; +import { AGENT_PROMPT, parsePromptRecord } from "@executablemd/agent/host"; import { parseDurableEvent } from "@executablemd/durable-streams"; import type { SidekickRecord } from "./history.ts"; import type { SidekickRequest } from "./model.ts"; diff --git a/packages/cli/src/repl/sidekick/testing.ts b/packages/cli/src/repl/sidekick/testing.ts index 29c6e7067..ab6def0da 100644 --- a/packages/cli/src/repl/sidekick/testing.ts +++ b/packages/cli/src/repl/sidekick/testing.ts @@ -27,7 +27,7 @@ import { import { useTesting, testHarnessInstallation } from "@executablemd/testing"; import type { TestResult } from "@executablemd/testing"; import { installTestAgentComponents } from "@executablemd/test-agent"; -import { installAgentComponents } from "@executablemd/core"; +import { installAgentComponents } from "@executablemd/agent/host"; import { resolveTestTarget } from "../../test-target.ts"; import type { ReplExecutionProfile } from "../../repl-profile.ts"; diff --git a/packages/cli/src/repl/todo/service.ts b/packages/cli/src/repl/todo/service.ts index d59d8b064..16874d49e 100644 --- a/packages/cli/src/repl/todo/service.ts +++ b/packages/cli/src/repl/todo/service.ts @@ -23,8 +23,8 @@ import { applyTodoDiff, parseTodo, todoDiff, TodoEditError } from "./document.ts import type { TodoDocument, TodoItem } from "./document.ts"; import { captureTodoSource } from "./source.ts"; import { TodoSourceError } from "./source.ts"; -import { Agent } from "@executablemd/core"; -import type { AgentPromptEvent } from "@executablemd/core"; +import { Agent } from "@executablemd/agent/api"; +import type { AgentPromptEvent } from "@executablemd/agent/api"; interface TodoObservation { readonly origin: "human" | "sidekick"; diff --git a/packages/cli/src/repl/usage.ts b/packages/cli/src/repl/usage.ts index a028f189b..8b84e1646 100644 --- a/packages/cli/src/repl/usage.ts +++ b/packages/cli/src/repl/usage.ts @@ -1,4 +1,4 @@ -import type { PromptRecord } from "@executablemd/core/host"; +import type { PromptRecord } from "@executablemd/agent/host"; import { inertCommandText } from "./command-output.ts"; type Usage = NonNullable; diff --git a/packages/cli/src/syntax.ts b/packages/cli/src/syntax.ts index 07c46c58d..1cd10cd68 100644 --- a/packages/cli/src/syntax.ts +++ b/packages/cli/src/syntax.ts @@ -32,12 +32,8 @@ import { scoped } from "effection"; import { Component, Syntax } from "@executablemd/core/api"; import { useSyntax } from "@executablemd/core/host"; import type { Operation } from "effection"; -import { - agentIdentityComponents, - inspectSyntax, - renderSyntaxMarkdown, - useAgentComponents, -} from "@executablemd/core"; +import { inspectSyntax, renderSyntaxMarkdown } from "@executablemd/core"; +import { agentIdentityComponents, useAgentComponents } from "@executablemd/agent/host"; import type { SyntaxSymbols } from "@executablemd/core"; import { useTestingComponents } from "@executablemd/testing"; import { useWebComponents } from "@executablemd/web"; diff --git a/packages/cli/src/testing-host.ts b/packages/cli/src/testing-host.ts index 86be9f560..41bc71793 100644 --- a/packages/cli/src/testing-host.ts +++ b/packages/cli/src/testing-host.ts @@ -35,12 +35,8 @@ import { API, useHostFiles } from "@executablemd/runtime"; import { installWebElicitation } from "@executablemd/web"; import { ensure, Err, Ok, until, useScope } from "effection"; import type { Operation, Result, Scope } from "effection"; -import { - agentIdentityComponents, - fileSource, - inlineSource, - installAgentComponents, -} from "@executablemd/core"; +import { fileSource, inlineSource } from "@executablemd/core"; +import { agentIdentityComponents, installAgentComponents } from "@executablemd/agent/host"; import type { RootDocumentSource } from "@executablemd/core"; import { executeInstalled, installAnswerProvider } from "@executablemd/core/host"; import { mkdir, rm } from "node:fs/promises"; diff --git a/packages/cli/src/workflow-agent.ts b/packages/cli/src/workflow-agent.ts index d78a4321f..84542859b 100644 --- a/packages/cli/src/workflow-agent.ts +++ b/packages/cli/src/workflow-agent.ts @@ -97,13 +97,10 @@ import { } from "@executablemd/acp/embedded-adapters"; import type { EmbeddedAdapters } from "@executablemd/acp/embedded-adapters"; import type { PromptUsageHost } from "@executablemd/acp"; -import { - installAgentComponents, - installPermissionMode, - registerAgentProvider, -} from "@executablemd/core"; -import type { AgentProviderFactory } from "@executablemd/core"; -import { useAgentPromptPublisher } from "@executablemd/core/host"; +import { registerAgentProvider } from "@executablemd/agent/api"; +import { installAgentComponents, installPermissionMode } from "@executablemd/agent/host"; +import type { AgentProviderFactory } from "@executablemd/agent/api"; +import { useAgentPromptPublisher } from "@executablemd/agent/host"; import { agentSessionKey, createWorkflowPromptPublisher, diff --git a/packages/cli/tests/adversarial-diagnosis.test.ts b/packages/cli/tests/adversarial-diagnosis.test.ts index 29bfa7b1b..d966af123 100644 --- a/packages/cli/tests/adversarial-diagnosis.test.ts +++ b/packages/cli/tests/adversarial-diagnosis.test.ts @@ -6,12 +6,8 @@ import { scoped, spawn } from "effection"; import type { Operation } from "effection"; import { join, resolve } from "node:path"; import { ensureDir, readTextFile, writeTextFile } from "@effectionx/fs"; -import { - collect, - agentIdentityComponents, - registerComponents, - useNormalizedOutput, -} from "@executablemd/core"; +import { collect, registerComponents, useNormalizedOutput } from "@executablemd/core"; +import { agentIdentityComponents } from "@executablemd/agent/host"; import { API, cwd, Permissions, realpath, useHostFiles } from "@executablemd/runtime"; import { InMemoryStream } from "@executablemd/durable-streams"; import { z } from "zod"; diff --git a/packages/cli/tests/adversarial-session-continuity.test.ts b/packages/cli/tests/adversarial-session-continuity.test.ts index 39a35bee8..8206ba899 100644 --- a/packages/cli/tests/adversarial-session-continuity.test.ts +++ b/packages/cli/tests/adversarial-session-continuity.test.ts @@ -9,17 +9,11 @@ import { randomUUID } from "node:crypto"; import { tmpdir } from "node:os"; import { join, resolve } from "node:path"; import { z } from "zod"; -import { - Agent, - agentIdentityComponents, - collect, - configurationOf, - Elicitation, - installAgentComponents, - registerComponents, - useNormalizedOutput, -} from "@executablemd/core"; -import type { AgentPromptEvent, Json, Session } from "@executablemd/core"; +import { collect, Elicitation, registerComponents, useNormalizedOutput } from "@executablemd/core"; +import { Agent, configurationOf } from "@executablemd/agent/api"; +import { agentIdentityComponents, installAgentComponents } from "@executablemd/agent/host"; +import type { Json } from "@executablemd/core"; +import type { AgentPromptEvent, Session } from "@executablemd/agent/api"; import { executeInstalled } from "@executablemd/core/host"; import { Permissions, useHostFiles } from "@executablemd/runtime"; import { InMemoryStream } from "@executablemd/durable-streams"; diff --git a/packages/cli/tests/agent-certification.test.ts b/packages/cli/tests/agent-certification.test.ts index d5ddf6a01..0ab81f729 100644 --- a/packages/cli/tests/agent-certification.test.ts +++ b/packages/cli/tests/agent-certification.test.ts @@ -266,7 +266,8 @@ describe("nested qualification teardown", { sanitizeOps: false, sanitizeResource yield* withCertificationFixture(function* (f) { yield* writeTextFile(join(f.dir, "package.json"), JSON.stringify({ type: "module" })); const faultSource = ` -import {AgentProviders,content} from "@executablemd/core"; +import {content} from "@executablemd/core"; +import {AgentProviders} from "@executablemd/agent/api"; import {ensure,sleep} from ${JSON.stringify(import.meta.resolve("effection"))}; import {writeTextFile} from ${JSON.stringify(import.meta.resolve("@effectionx/fs"))}; export function* install() { diff --git a/packages/cli/tests/agent-config.test.ts b/packages/cli/tests/agent-config.test.ts index 91ccdee7a..755ec5700 100644 --- a/packages/cli/tests/agent-config.test.ts +++ b/packages/cli/tests/agent-config.test.ts @@ -9,7 +9,7 @@ */ import { describe, it } from "@executablemd/test-support/bdd"; import { expect } from "@executablemd/test-support/expect"; -import type { PermissionMode } from "@executablemd/core"; +import type { PermissionMode } from "@executablemd/agent/api"; import { resolveAgentConfig } from "../src/agent-config.ts"; import type { AgentFlags } from "../src/agent-config.ts"; diff --git a/packages/cli/tests/agent-options.test.ts b/packages/cli/tests/agent-options.test.ts index 3e29dee13..98a47f70d 100644 --- a/packages/cli/tests/agent-options.test.ts +++ b/packages/cli/tests/agent-options.test.ts @@ -10,7 +10,7 @@ */ import { describe, it } from "@executablemd/test-support/bdd"; import { expect } from "@executablemd/test-support/expect"; -import type { AgentOptions } from "@executablemd/core"; +import type { AgentOptions } from "@executablemd/agent/api"; import { renderAgentOptions, renderAgentOptionsJson, scanAgentArgs } from "../src/agent-options.ts"; /** One command line, as the dispatcher passes it: the command still at head. */ diff --git a/packages/cli/tests/agent-session-coordinator.test.ts b/packages/cli/tests/agent-session-coordinator.test.ts index bf852d4fa..fd145eb8f 100644 --- a/packages/cli/tests/agent-session-coordinator.test.ts +++ b/packages/cli/tests/agent-session-coordinator.test.ts @@ -17,13 +17,13 @@ import { randomUUID } from "node:crypto"; import { tmpdir } from "node:os"; import { dirname, join } from "node:path"; import { fileURLToPath } from "node:url"; -import { Agent } from "@executablemd/core"; +import { Agent } from "@executablemd/agent/api"; import type { AgentLaunchRequest, AgentLaunchCoordinator, LaunchRecord, PreparedLaunchRecord, -} from "@executablemd/core"; +} from "@executablemd/agent/api"; import { API, createDenoAgentSessionCoordinator, diff --git a/packages/cli/tests/agent-usage-calibration.test.ts b/packages/cli/tests/agent-usage-calibration.test.ts index 8f9acee3e..c4876a877 100644 --- a/packages/cli/tests/agent-usage-calibration.test.ts +++ b/packages/cli/tests/agent-usage-calibration.test.ts @@ -30,7 +30,7 @@ import { codexNative, nativeComparison, } from "../../../examples/agent-usage/evidence.ts"; -import type { PromptUsage } from "@executablemd/core"; +import type { PromptUsage } from "@executablemd/agent/api"; import { readdir as readdirOf, writeTextFile } from "@effectionx/fs"; const CHECKOUT = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..", ".."); diff --git a/packages/cli/tests/fixtures/host-agent.ts b/packages/cli/tests/fixtures/host-agent.ts index 26dab1753..ede2c4617 100644 --- a/packages/cli/tests/fixtures/host-agent.ts +++ b/packages/cli/tests/fixtures/host-agent.ts @@ -6,7 +6,8 @@ import { readdir, readFile } from "node:fs/promises"; import { until } from "effection"; import { workflowProviderSessions } from "@executablemd/workflow/deno"; import { DatabaseSync } from "node:sqlite"; -import { agentIdentityComponents, collect, retainedSource } from "@executablemd/core"; +import { collect, retainedSource } from "@executablemd/core"; +import { agentIdentityComponents } from "@executablemd/agent/host"; import { executeInstalled } from "@executablemd/core/host"; import { API, useHostFiles } from "@executablemd/runtime"; import { createEmbeddedAdapters } from "@executablemd/acp/embedded-adapters"; diff --git a/packages/cli/tests/fixtures/repl/contributed-plugin.ts b/packages/cli/tests/fixtures/repl/contributed-plugin.ts index 9231cf377..bafdbfeb1 100644 --- a/packages/cli/tests/fixtures/repl/contributed-plugin.ts +++ b/packages/cli/tests/fixtures/repl/contributed-plugin.ts @@ -1,7 +1,8 @@ import { createContext, ensure, sleep } from "effection"; import type { Operation } from "effection"; import { content, contributeDocumentation, formDispatcher } from "@executablemd/core"; -import { AgentConversationProvider, Plugin } from "@executablemd/core/api"; +import { Plugin } from "@executablemd/core/api"; +import { AgentConversationProvider } from "@executablemd/agent/api"; import type { ReplPluginInstallation } from "../../../api.ts"; import { createDurableOperation } from "@executablemd/durable-streams"; diff --git a/packages/cli/tests/fixtures/repl/issue-883/recovery-phase.ts b/packages/cli/tests/fixtures/repl/issue-883/recovery-phase.ts index 165e886b8..b0144d1c3 100644 --- a/packages/cli/tests/fixtures/repl/issue-883/recovery-phase.ts +++ b/packages/cli/tests/fixtures/repl/issue-883/recovery-phase.ts @@ -28,7 +28,7 @@ import { ensure, main, Ok, race, spawn, suspend, until, withResolvers } from "ef import type { Operation, Result } from "effection"; import { parseDurableEvent, serializeDurableEvent } from "@executablemd/durable-streams"; import type { DurableEvent } from "@executablemd/durable-streams"; -import { AGENT_PROMPT, parsePromptRecord } from "@executablemd/core/host"; +import { AGENT_PROMPT, parsePromptRecord } from "@executablemd/agent/host"; import { ReplHost } from "../../../../src/repl/host.ts"; import { installReplHost } from "../../../../src/repl-assembly.ts"; @@ -79,7 +79,7 @@ import { resolveSessionDetails, } from "@executablemd/acp"; import type { AcpxProviderDependencies } from "@executablemd/acp"; -import { installAgentComponents } from "@executablemd/core"; +import { installAgentComponents } from "@executablemd/agent/host"; import type { FakeAcp } from "../../../support/fake-acp.ts"; /** The conversation and response a reply's control belongs to. */ diff --git a/packages/cli/tests/fixtures/repl/reference.ts b/packages/cli/tests/fixtures/repl/reference.ts index fb4d6575e..89a79ccdb 100644 --- a/packages/cli/tests/fixtures/repl/reference.ts +++ b/packages/cli/tests/fixtures/repl/reference.ts @@ -17,15 +17,17 @@ import { readTextFile } from "@effectionx/fs"; import { fileURLToPath } from "node:url"; import { InMemoryStream } from "@executablemd/durable-streams"; import type { DurableEvent, Json } from "@executablemd/durable-streams"; -import { Agent, collect, Elicitation, installAgentComponents } from "@executablemd/core"; +import { collect, Elicitation } from "@executablemd/core"; +import { Agent } from "@executablemd/agent/api"; +import { installAgentComponents } from "@executablemd/agent/host"; +import type { ElicitationRequest } from "@executablemd/core"; import type { AgentPromptEvent, AgentProviderFactory, - ElicitationRequest, PermissionOption, PromptOptions, Session, -} from "@executablemd/core"; +} from "@executablemd/agent/api"; import { executeInstalled } from "@executablemd/core/host"; import { inlineSource } from "@executablemd/core"; import type { Operation, Stream } from "effection"; diff --git a/packages/cli/tests/plan-command-document.test.ts b/packages/cli/tests/plan-command-document.test.ts index d87ea530f..17b8626b9 100644 --- a/packages/cli/tests/plan-command-document.test.ts +++ b/packages/cli/tests/plan-command-document.test.ts @@ -28,12 +28,8 @@ import { ensureDir, rm } from "@effectionx/fs"; import { randomUUID } from "node:crypto"; import { tmpdir } from "node:os"; import { join } from "node:path"; -import { - agentIdentityComponents, - installAgentComponents, - retainedSource, - useNormalizedOutput, -} from "@executablemd/core"; +import { retainedSource, useNormalizedOutput } from "@executablemd/core"; +import { agentIdentityComponents, installAgentComponents } from "@executablemd/agent/host"; import type { DocumentValidation, ElicitationRequest, diff --git a/packages/cli/tests/plan-component.test.ts b/packages/cli/tests/plan-component.test.ts index 9545a705e..dfc212fa3 100644 --- a/packages/cli/tests/plan-component.test.ts +++ b/packages/cli/tests/plan-component.test.ts @@ -23,13 +23,8 @@ import { readdir } from "node:fs/promises"; import { tmpdir } from "node:os"; import { join } from "node:path"; import { forEach } from "@effectionx/stream-helpers"; -import { - agentIdentityComponents, - collect, - installAgentComponents, - retainedSource, - useNormalizedOutput, -} from "@executablemd/core"; +import { collect, retainedSource, useNormalizedOutput } from "@executablemd/core"; +import { agentIdentityComponents, installAgentComponents } from "@executablemd/agent/host"; import type { Json, SyntaxSymbols } from "@executablemd/core"; import { content, registerComponents, validateDocument } from "@executablemd/core"; import { executeInstalled, sourceDigest } from "@executablemd/core/host"; diff --git a/packages/cli/tests/prompt-usage-hosts.test.ts b/packages/cli/tests/prompt-usage-hosts.test.ts index aab1e3014..72f239071 100644 --- a/packages/cli/tests/prompt-usage-hosts.test.ts +++ b/packages/cli/tests/prompt-usage-hosts.test.ts @@ -22,9 +22,11 @@ import { join } from "node:path"; import { fileURLToPath } from "node:url"; import { tmpdir } from "node:os"; import { useHostFiles } from "@executablemd/runtime"; -import { agentIdentityComponents, collect, retainedSource } from "@executablemd/core"; -import type { PromptUsage } from "@executablemd/core"; -import { executeInstalled, parsePromptRecord, useAgentConversation } from "@executablemd/core/host"; +import { collect, retainedSource } from "@executablemd/core"; +import { agentIdentityComponents } from "@executablemd/agent/host"; +import type { PromptUsage } from "@executablemd/agent/api"; +import { executeInstalled } from "@executablemd/core/host"; +import { parsePromptRecord, useAgentConversation } from "@executablemd/agent/host"; import { withWorkflowWorkspace } from "@executablemd/workflow/deno"; import type { AcpxProviderDependencies, PromptUsageHost } from "@executablemd/acp"; import { createEmbeddedAdapters } from "@executablemd/acp/embedded-adapters"; diff --git a/packages/cli/tests/repl-agent-execution.test.ts b/packages/cli/tests/repl-agent-execution.test.ts index 03957916b..f6ef5860e 100644 --- a/packages/cli/tests/repl-agent-execution.test.ts +++ b/packages/cli/tests/repl-agent-execution.test.ts @@ -35,14 +35,9 @@ import { serializeDurableEvent, } from "@executablemd/durable-streams"; import type { DurableEvent } from "@executablemd/durable-streams"; -import { - Agent, - agentIdentityComponents, - Elicitation, - installAgentComponents, - registerComponents, - useTempFileCompiler, -} from "@executablemd/core"; +import { Elicitation, registerComponents, useTempFileCompiler } from "@executablemd/core"; +import { Agent } from "@executablemd/agent/api"; +import { agentIdentityComponents, installAgentComponents } from "@executablemd/agent/host"; import type { AgentPromptEvent, PermissionMode, @@ -51,8 +46,8 @@ import type { PermissionRequest, PromptOptions, Session, -} from "@executablemd/core"; -import type { AgentProviderFactory } from "@executablemd/core"; +} from "@executablemd/agent/api"; +import type { AgentProviderFactory } from "@executablemd/agent/api"; import type { ExecutionInstallation } from "@executablemd/core/host"; import { API } from "@executablemd/runtime"; diff --git a/packages/cli/tests/repl-agent-interface.test.ts b/packages/cli/tests/repl-agent-interface.test.ts index ce9bbb69c..46a5d56a3 100644 --- a/packages/cli/tests/repl-agent-interface.test.ts +++ b/packages/cli/tests/repl-agent-interface.test.ts @@ -19,12 +19,9 @@ import { race, scoped, sleep, until as untilResolved, useScope, withResolvers } import type { Operation, Result, Stream } from "effection"; import { DurableContext, InMemoryStream } from "@executablemd/durable-streams"; import { DEFAULT_AGENT_NAME } from "@executablemd/acp"; -import { - Agent, - agentIdentityComponents, - installAgentComponents, - useTempFileCompiler, -} from "@executablemd/core"; +import { useTempFileCompiler } from "@executablemd/core"; +import { Agent } from "@executablemd/agent/api"; +import { agentIdentityComponents, installAgentComponents } from "@executablemd/agent/host"; import type { AgentPromptEvent, AgentProviderFactory, @@ -34,7 +31,7 @@ import type { PermissionRequest, PromptOptions, Session, -} from "@executablemd/core"; +} from "@executablemd/agent/api"; import type { ExecutionInstallation } from "@executablemd/core/host"; import { ordinaryGeneratedSelection } from "../src/evaluation-profile.ts"; diff --git a/packages/cli/tests/repl-execution.test.ts b/packages/cli/tests/repl-execution.test.ts index 82e7495c3..4acab24fd 100644 --- a/packages/cli/tests/repl-execution.test.ts +++ b/packages/cli/tests/repl-execution.test.ts @@ -49,13 +49,8 @@ import { openReplSession, submitReplEntry } from "../src/repl/session.ts"; import type { ExpansionController } from "../src/repl/expansion.ts"; import type { ReplSession } from "../src/repl/session.ts"; import type { ReplQuestion } from "../src/repl/elicitation.ts"; -import { - Component, - DocumentOutput, - Elicitation, - Execution, - installAgentComponents, -} from "@executablemd/core"; +import { Component, DocumentOutput, Elicitation, Execution } from "@executablemd/core"; +import { installAgentComponents } from "@executablemd/agent/host"; import { REFERENCE_DIRECTORY, referenceEvents, diff --git a/packages/cli/tests/repl-headless-clients.test.ts b/packages/cli/tests/repl-headless-clients.test.ts index bae9aeb55..d4e7334db 100644 --- a/packages/cli/tests/repl-headless-clients.test.ts +++ b/packages/cli/tests/repl-headless-clients.test.ts @@ -20,7 +20,7 @@ import { useReplElicitation } from "../src/repl/elicitation.ts"; import { action, until } from "effection"; import { Elicitation } from "@executablemd/core"; import type { Scope } from "effection"; -import type { AgentPromptEvent } from "@executablemd/core"; +import type { AgentPromptEvent } from "@executablemd/agent/api"; const conditional = { type: "object", diff --git a/packages/cli/tests/repl-headless.test.ts b/packages/cli/tests/repl-headless.test.ts index 05fad156c..eb00623ba 100644 --- a/packages/cli/tests/repl-headless.test.ts +++ b/packages/cli/tests/repl-headless.test.ts @@ -20,8 +20,9 @@ import { attachmentDescriptor, requestAttachment } from "../src/sidekick-acp/cli import { Reply, SidekickTransport } from "../src/sidekick-acp/protocol.ts"; import { z } from "zod"; import { childAddressPath, useHeadlessChildren } from "../src/headless/host.ts"; -import { agentIdentityComponents, installAgentComponents } from "@executablemd/core"; -import { executeInstalled, useAgentConversation } from "@executablemd/core/host"; +import { agentIdentityComponents, installAgentComponents } from "@executablemd/agent/host"; +import { executeInstalled } from "@executablemd/core/host"; +import { useAgentConversation } from "@executablemd/agent/host"; import { InMemoryStream } from "@executablemd/durable-streams"; import { ensureDir, rm, writeTextFile } from "@effectionx/fs"; import { join } from "node:path"; diff --git a/packages/cli/tests/repl-sidekick-acp.test.ts b/packages/cli/tests/repl-sidekick-acp.test.ts index 0c1fb35ba..001cba258 100644 --- a/packages/cli/tests/repl-sidekick-acp.test.ts +++ b/packages/cli/tests/repl-sidekick-acp.test.ts @@ -13,7 +13,8 @@ import { copyFile, ensureDir, exists, readTextFile, writeTextFile } from "@effec import { exec, ProcessApi, Stdio } from "@effectionx/process"; import { selectJson } from "@executablemd/core/host"; import { openReplSession } from "../src/repl/session.ts"; -import { Agent, Component, Execution } from "@executablemd/core"; +import { Component, Execution } from "@executablemd/core"; +import { Agent } from "@executablemd/agent/api"; import { API } from "@executablemd/runtime"; import { createHash } from "node:crypto"; import { createRequire } from "node:module"; @@ -114,7 +115,7 @@ import { parseEntryRecords, parseSidekickRecord, } from "../src/repl/sidekick/history.ts"; -import { AGENT_PROMPT, AGENT_PROMPT_REPLY } from "@executablemd/core/host"; +import { AGENT_PROMPT, AGENT_PROMPT_REPLY } from "@executablemd/agent/host"; import { parseDurableEvent } from "@executablemd/durable-streams"; import { Descriptor, diff --git a/packages/cli/tests/repl-sidekick-controls.test.ts b/packages/cli/tests/repl-sidekick-controls.test.ts index 29daa0c50..2e8b4fa4d 100644 --- a/packages/cli/tests/repl-sidekick-controls.test.ts +++ b/packages/cli/tests/repl-sidekick-controls.test.ts @@ -48,16 +48,15 @@ import type { Operation, Result } from "effection"; import { parseDurableEvent, InMemoryStream } from "@executablemd/durable-streams"; import type { DurableEvent, Json } from "@executablemd/durable-streams"; import { - Agent, Syntax, - agentIdentityComponents, - installAgentComponents, useNormalizedOutput, Component, Execution, retainedSource, useTempFileCompiler, } from "@executablemd/core"; +import { Agent } from "@executablemd/agent/api"; +import { agentIdentityComponents, installAgentComponents } from "@executablemd/agent/host"; import type { SyntaxSymbols, FunctionComponentDefinition } from "@executablemd/core"; import { executeInstalled } from "@executablemd/core/host"; import type { ExecutionInstallation, GeneratedXmdRootResult } from "@executablemd/core/host"; diff --git a/packages/cli/tests/repl-sidekick-dispatch.test.ts b/packages/cli/tests/repl-sidekick-dispatch.test.ts index 99b1fdf4f..f77fbc576 100644 --- a/packages/cli/tests/repl-sidekick-dispatch.test.ts +++ b/packages/cli/tests/repl-sidekick-dispatch.test.ts @@ -3,7 +3,7 @@ import { expect } from "@executablemd/test-support/expect"; import { ensure, Ok, scoped, spawn, suspend, withResolvers } from "effection"; import type { Operation, Result } from "effection"; import { parseDurableEvent } from "@executablemd/durable-streams"; -import { AGENT_PROMPT } from "@executablemd/core/host"; +import { AGENT_PROMPT } from "@executablemd/agent/host"; import { coldReservations, retainResolution } from "../src/repl/sidekick/admission.ts"; import type { SidekickRecord } from "../src/repl/sidekick/history.ts"; import { projectSidekick } from "../src/repl/sidekick/model.ts"; diff --git a/packages/cli/tests/repl-sidekick-recovery.test.ts b/packages/cli/tests/repl-sidekick-recovery.test.ts index ff2b64194..49cd209a6 100644 --- a/packages/cli/tests/repl-sidekick-recovery.test.ts +++ b/packages/cli/tests/repl-sidekick-recovery.test.ts @@ -56,8 +56,8 @@ import { withResolvers, } from "effection"; import type { Operation, Result, Stream, Subscription } from "effection"; -import { Agent } from "@executablemd/core"; -import type { AgentPromptEvent } from "@executablemd/core"; +import { Agent } from "@executablemd/agent/api"; +import type { AgentPromptEvent } from "@executablemd/agent/api"; import { Plugin } from "@executablemd/core/api"; import type { ReplPluginInstallation } from "../api.ts"; import type { AgentSessionOwnershipAdministration } from "@executablemd/runtime"; @@ -73,7 +73,7 @@ import type { Harness } from "./fixtures/repl/issue-883/sidekick-harness.ts"; import type { ScriptedTurn } from "./support/fake-acp.ts"; import { useTempFileCompiler, Elicitation } from "@executablemd/core"; import { parseDurableEvent, serializeDurableEvent } from "@executablemd/durable-streams"; -import { AGENT_PROMPT, parsePromptRecord } from "@executablemd/core/host"; +import { AGENT_PROMPT, parsePromptRecord } from "@executablemd/agent/host"; import type { DurableEvent } from "@executablemd/durable-streams"; import { diff --git a/packages/cli/tests/repl-sidekick-resume.test.ts b/packages/cli/tests/repl-sidekick-resume.test.ts index f7a653e76..5c6c27a05 100644 --- a/packages/cli/tests/repl-sidekick-resume.test.ts +++ b/packages/cli/tests/repl-sidekick-resume.test.ts @@ -18,9 +18,10 @@ import { expect } from "@executablemd/test-support/expect"; import { Ok, scoped } from "effection"; import type { Operation, Result } from "effection"; import { InMemoryStream } from "@executablemd/durable-streams"; -import { Agent } from "@executablemd/core"; -import { useAgentConversation } from "@executablemd/core/host"; -import type { AgentConversation, ExecutionInstallation } from "@executablemd/core/host"; +import { Agent } from "@executablemd/agent/api"; +import { useAgentConversation } from "@executablemd/agent/host"; +import type { ExecutionInstallation } from "@executablemd/core/host"; +import type { AgentConversation } from "@executablemd/agent/host"; import { sidekickAssembly } from "../src/repl/sidekick/assembly.ts"; import { createFakeAcp, makeRegistry, makeStore } from "./support/fake-acp.ts"; diff --git a/packages/cli/tests/repl-todo-context.test.ts b/packages/cli/tests/repl-todo-context.test.ts index f80bb55c5..e709345bb 100644 --- a/packages/cli/tests/repl-todo-context.test.ts +++ b/packages/cli/tests/repl-todo-context.test.ts @@ -1,10 +1,11 @@ -import { Agent, isJsonObject, parseJson } from "@executablemd/core"; +import { isJsonObject, parseJson } from "@executablemd/core"; +import { Agent } from "@executablemd/agent/api"; import { Plugin } from "@executablemd/core/api"; import { describe, it } from "@executablemd/test-support/bdd"; import { expect } from "@executablemd/test-support/expect"; import { ensure, Ok, resource, scoped, spawn, withResolvers } from "effection"; import type { Operation, Result, Stream, Subscription } from "effection"; -import type { AgentPromptEvent } from "@executablemd/core"; +import type { AgentPromptEvent } from "@executablemd/agent/api"; import type { ReplPluginInstallation } from "../api.ts"; import { writeTextFile } from "@effectionx/fs"; import { useHostFiles } from "@executablemd/runtime"; diff --git a/packages/cli/tests/run-composition-deno.test.ts b/packages/cli/tests/run-composition-deno.test.ts index 3a784c93f..1fde4023e 100644 --- a/packages/cli/tests/run-composition-deno.test.ts +++ b/packages/cli/tests/run-composition-deno.test.ts @@ -24,14 +24,9 @@ import { join } from "node:path"; import process from "node:process"; import { API, NativeLauncher, useHostFiles } from "@executablemd/runtime"; import { InMemoryStream } from "@executablemd/durable-streams"; -import { - Agent, - collect, - execute, - inlineSource, - installAgentComponents, - registerAgentProvider, -} from "@executablemd/core"; +import { collect, execute, inlineSource } from "@executablemd/core"; +import { Agent, registerAgentProvider } from "@executablemd/agent/api"; +import { installAgentComponents } from "@executablemd/agent/host"; import { useTempDirectory } from "@executablemd/test-support/temp"; import { deriveSessionKey, sessionCandidates } from "../../acp/src/session-key.ts"; import { useCompositionComponents } from "@executablemd/git"; diff --git a/packages/cli/tests/run-composition-nested.test.ts b/packages/cli/tests/run-composition-nested.test.ts index 2ec4d878c..d233954d4 100644 --- a/packages/cli/tests/run-composition-nested.test.ts +++ b/packages/cli/tests/run-composition-nested.test.ts @@ -20,7 +20,8 @@ import { join } from "node:path"; import process from "node:process"; import { API, useHostFiles } from "@executablemd/runtime"; import { InMemoryStream } from "@executablemd/durable-streams"; -import { collect, execute, inlineSource, installAgentComponents } from "@executablemd/core"; +import { collect, execute, inlineSource } from "@executablemd/core"; +import { installAgentComponents } from "@executablemd/agent/host"; import { runCli } from "@executablemd/test-support/launch"; import { useTempDirectory } from "@executablemd/test-support/temp"; import { useCompositionComponents } from "@executablemd/git"; diff --git a/packages/cli/tests/testing-execution-host.test.ts b/packages/cli/tests/testing-execution-host.test.ts index 34373b254..79f5539f9 100644 --- a/packages/cli/tests/testing-execution-host.test.ts +++ b/packages/cli/tests/testing-execution-host.test.ts @@ -571,7 +571,7 @@ const INSPECTION_PROBE = doc( '', "", "```js ephemeral eval", - 'import { Agent } from "@executablemd/core";', + 'import { Agent } from "@executablemd/agent/api";', 'const choices = yield* Agent.operations.options("codex", { model: "sol" });', 'if (choices.agent !== "codex" || choices.model?.selected !== "sol" ||', ' choices.model?.options.map((choice) => choice.id).join(",") !== "small,sol" ||', diff --git a/packages/cli/tests/workflow-agent-sessions.test.ts b/packages/cli/tests/workflow-agent-sessions.test.ts index ffffa2e8b..090629c48 100644 --- a/packages/cli/tests/workflow-agent-sessions.test.ts +++ b/packages/cli/tests/workflow-agent-sessions.test.ts @@ -28,12 +28,8 @@ import { createEmbeddedAdapters } from "@executablemd/acp/embedded-adapters"; import { DatabaseSync } from "node:sqlite"; import { dirname, join, relative as relativePath } from "node:path"; import { fileURLToPath } from "node:url"; -import { - registerComponents, - agentIdentityComponents, - collect, - retainedSource, -} from "@executablemd/core"; +import { registerComponents, collect, retainedSource } from "@executablemd/core"; +import { agentIdentityComponents } from "@executablemd/agent/host"; import { executeInstalled } from "@executablemd/core/host"; import type { Json } from "@executablemd/durable-streams"; import { API, useHostFiles } from "@executablemd/runtime"; diff --git a/packages/cli/tests/workflow-agent.test.ts b/packages/cli/tests/workflow-agent.test.ts index 2b4eeaca2..b06bdbc56 100644 --- a/packages/cli/tests/workflow-agent.test.ts +++ b/packages/cli/tests/workflow-agent.test.ts @@ -37,7 +37,7 @@ import { } from "@executablemd/workflow/deno"; import type { WorkflowRequestBound } from "@executablemd/workflow/deno"; import { executeInstalled } from "@executablemd/core/host"; -import { agentIdentityComponents } from "@executablemd/core"; +import { agentIdentityComponents } from "@executablemd/agent/host"; import { useWorkflowAgentProfile, WORKFLOW_SESSION_INSTRUCTIONS } from "../src/workflow-agent.ts"; import type { EmbeddedAdapters } from "@executablemd/acp/embedded-adapters"; import { createEmbeddedAdapters } from "@executablemd/acp/embedded-adapters"; diff --git a/packages/cli/tests/workflow-suspension.test.ts b/packages/cli/tests/workflow-suspension.test.ts index 07ab45ffc..260cc124d 100644 --- a/packages/cli/tests/workflow-suspension.test.ts +++ b/packages/cli/tests/workflow-suspension.test.ts @@ -58,13 +58,10 @@ import { GitQuery } from "@executablemd/git/api"; import type { WorkflowRunDatabase } from "@executablemd/workflow"; import { workflowRunPath } from "@executablemd/workflow/deno"; import { withWorkflowWorkspace, WORKSPACE_FILE } from "@executablemd/workflow/deno"; -import { Agent, installAgentComponents, sessionOf } from "@executablemd/core"; -import type { - AgentPromptEvent, - Json as CoreJson, - PromptOptions, - Session, -} from "@executablemd/core"; +import { Agent, sessionOf } from "@executablemd/agent/api"; +import { installAgentComponents } from "@executablemd/agent/host"; +import type { Json as CoreJson } from "@executablemd/core"; +import type { AgentPromptEvent, PromptOptions, Session } from "@executablemd/agent/api"; import type { Stream } from "effection"; import { createHash } from "node:crypto"; import { establishDefinition } from "../src/workflow-definition.ts"; @@ -820,7 +817,7 @@ decision: {decision.proceed} * asserts all three appear among the effect types the run actually journaled, * so a renamed effect fails the case rather than silently counting zero. */ -const PROMPT_EFFECT = "agent_prompt"; // packages/core/src/agent/journal.ts +const PROMPT_EFFECT = "agent_prompt"; // packages/agent/src/journal.ts const EVALUATION_EFFECT = "generated_xmd"; // packages/core/src/generated-xmd.ts const FILE_EFFECT = WORKSPACE_FILE; diff --git a/packages/core/api.ts b/packages/core/api.ts index 0456b2625..689d4993d 100644 --- a/packages/core/api.ts +++ b/packages/core/api.ts @@ -46,81 +46,6 @@ export { } from "./src/plugin-apis.ts"; export type { ActivePluginsApi, DocumentApi, RootMetadataApi } from "./src/plugin-apis.ts"; -/** - * The Agent Api, and the contracts its operations are written in. - * - * A Plugin composes agent work the same way it composes a document: around - * these operations, in the ordinary order. What it reaches here is - * provider-neutral — exact choice IDs, normalized options, and the session a - * provider issued — and never a protocol type belonging to whichever provider - * happens to be installed. - */ -export { Agent } from "./src/agent/agent-api.ts"; -export type { - AgentApi, - AgentOption, - AgentOptions, - AgentOptionSet, - AgentOptionsRequest, - AgentPromptEvent, - PromptImage, - PermissionMode, - PermissionOption, - PermissionOutcome, - PermissionRequest, - PromptOptions, - Session, - SessionIdentity, - SessionConfiguration, -} from "./src/agent/agent-api.ts"; -export type { AgentSessionRequest } from "./src/agent/session-request.ts"; -/** - * The provider a retained conversation does its work through. - * - * Here, beside `Agent`, because it is the other half of the same boundary: a - * host that serves saved conversations installs this object in its provider's - * own scope, and the conversation reads it once in its own. Ordinary `` - * and `` keep composing through `Agent`, which is what middleware is - * for; a chat does not, because what holds it to the configuration it was - * created under cannot be something a handler may route around. - * - * A held turn is captured here and reached through this object's own receiver. - * Its content and cold stream are composed by ordinary outer `Agent.prompt` - * middleware above a turn-local terminal bound to this provider, the selected - * agent and the exact checked Session — so composition changes the text and the - * stream, never which provider answers. What this provider receives is the text - * the journal retains; a composition that changed the checked call is refused - * before any native work, and nothing routes through ordinary provider handlers - * as a fallback. Subscription-owned cleanup belongs to that conversation's turn. - * - * One name for the interface and the Context, as `Agent` already has. - */ -export { AgentConversationProvider } from "./src/agent/conversation-provider.ts"; -/** - * One authentic use of a conversation, and what a reader may ask about one. - * - * A use is a `Session`, so nothing composing around these operations has to - * know about it. `claimsConfiguration()` answers for any value; `isSessionUse()`, - * `sessionOf()` and `configurationOf()` answer for a value this build issued, - * and refuse a rebuilt, copied or foreign one rather than reading it as an - * ordinary session. - * - * Reading is not acting. Which installation a use belongs to, and whether it is - * the one this operation was authored with, are settled where the operation - * reaches the provider — through the coordinator core delivers there. So a - * handler may see what a use says and delegate it, and still cannot pair a - * conversation with settings of its own. - */ -export { - AgentSessionUseError, - claimsConfiguration, - configurationOf, - isSessionUse, - sessionOf, -} from "./src/agent/session-use.ts"; -export type { AgentSessionUse } from "./src/agent/session-use.ts"; -export type { AgentLaunchRequest } from "./src/agent/launch-request.ts"; - /** * The types the accepted `PluginInstallation` members are written in. * diff --git a/packages/core/deno.json b/packages/core/deno.json index fbb8bfb46..3cdec4b7b 100644 --- a/packages/core/deno.json +++ b/packages/core/deno.json @@ -22,7 +22,6 @@ "marked-terminal": "npm:marked-terminal@^7.3.0", "remark": "npm:remark@15", "remend": "npm:remend@^1.2.2", - "zod": "npm:zod@^4.3.6", "unist-util-select": "npm:unist-util-select@^5", "mdast-util-to-string": "npm:mdast-util-to-string@^4", "@secretlint/profiler": "npm:@secretlint/profiler@13.0.4", diff --git a/packages/core/host.ts b/packages/core/host.ts index 4dd5b5f0f..cc293f815 100644 --- a/packages/core/host.ts +++ b/packages/core/host.ts @@ -188,7 +188,32 @@ export { readElicitationAnswer, readElicitationSchema, } from "./src/elicit-journal.ts"; -export { retainsOptionalText } from "./src/secrets/policy.ts"; +export { clearsLiveOutput, retainsOptionalText } from "./src/secrets/policy.ts"; + +/** + * What a package that owns its own canonical durable effects reads from core. + * + * The Agent package journals each Prompt as core does its own effects: it + * stops on the same durability and filesystem failures, tells an invocation's + * teardown failure apart from the work it tore down, and attributes a record to + * the source owner core has in effect. These answer those questions without + * handing out the Context or the failure classes behind them. + */ +export { + durabilityFailure, + filesFatalFailure, + hasCause, + hasInvocationTeardown, +} from "./src/errors.ts"; +export { readSourceOwnerDescription } from "./src/source-owner.ts"; +/** + * Approved secret matches, and where approved copies of string fields land in + * the exact JSON text a host rendered for them. The scanner and the gate that + * enforce an approval stay core's own. + */ +export type { SecretSpan } from "./src/secrets/scanner.ts"; +export type { ApprovedMatch } from "./src/secrets/secret-placement.ts"; +export { placeApprovedCopies } from "./src/secrets/secret-placement.ts"; export { WorkflowBundleError } from "./src/components/bundle.ts"; export type { WorkflowBundleComponent, WorkflowComponentBundle } from "./src/components/bundle.ts"; @@ -196,7 +221,7 @@ export type { WorkflowBundleComponent, WorkflowComponentBundle } from "./src/com * Exact Markdown a trusted host declares to an execution — see * `src/components/declared-markdown.ts`. * - * The fifth act of infrastructure, and the same shape as the rest: plain + * Another act of infrastructure, and the same shape as the rest: plain * immutable data the host holds and passes. The host states the bytes, their * origin and their digest, and canonical core refuses the declaration if what * the host said about them is not what they say about themselves. `sourceDigest` @@ -235,7 +260,7 @@ export type { * Structural syntax a trusted host declares to an execution — see * `src/execution-declarations.ts`. * - * The seventh act of infrastructure, and the same shape as the rest: plain + * Another act of infrastructure, and the same shape as the rest: plain * immutable data the host holds and passes, beside the handler that expands it. * A declaration states a construct and the regions written directly inside it; * the installation that declares them supplies the one `expand` captured with @@ -271,20 +296,6 @@ export type { StructuralInput, } from "./src/execution-declarations.ts"; -/** - * Installing one Agent provider for the invocation that projects the content it - * covers. - * - * The sixth act of infrastructure, and the narrowest: a trusted host component - * that establishes a constrained ceiling around content it projects installs the - * provider *in* that invocation, exactly as `` does, because a - * provider installed in a frame nested inside it would be invisible to the very - * content it was selected for. Kept here for the reason the rest of this module - * is: nothing a document, a component or a middleware package reaches by - * importing `@executablemd/core` can install a provider for a region it did not - * author. - */ -export { installInvocationAgentProvider } from "./src/agent/launch-install.ts"; export { GeneratedXmdError } from "./src/generated-xmd.ts"; /** @@ -305,7 +316,7 @@ export { GeneratedXmdError } from "./src/generated-xmd.ts"; * * There is no siteless form: a root is evaluated by the execution that captured * the selection it runs under, through `HostExecution.evaluateGeneratedXmdRoot` - * or the same method on an `AgentConversation`. + * or the same method on an `AgentConversation` from `@executablemd/agent/host`. * * `GeneratedXmdRequest` is the whole of what a caller states: which evaluation * this is, the candidate bytes, which of the captured effect classes it may @@ -330,12 +341,6 @@ export type { ElicitChoiceSelection, } from "./src/approved-generated-source.ts"; export { HostExecutionError } from "./src/generated-root-owner.ts"; -export { - AgentConversationError, - AgentReplyWithheldError, - useAgentConversation, -} from "./src/agent/conversation.ts"; -export type { AgentConversation, AgentConversationRequest } from "./src/agent/conversation.ts"; /** * What an arriving generated root already says — see @@ -365,30 +370,6 @@ export type { AgentConversation, AgentConversationRequest } from "./src/agent/co export { GeneratedXmdPreviewError, previewGeneratedXmdRoot } from "./src/generated-xmd-preview.ts"; export type { GeneratedXmdRootPreview } from "./src/generated-xmd-preview.ts"; -/** - - * Where a completed Prompt publishes, for a host that retains something beside - * it. - * - * The fourth act of infrastructure, and the same shape as the three above: a - * value the host holds and passes. An ordinary run installs none and publishes - * exactly as it always did. A host that installs one moves the `agent_prompt` - * append inside the transaction it opened, so what it keeps beside that event - * commits with the event or not at all. - * - * Kept here for the reason the rest of this module is: nothing a document, a - * component or a middleware package reaches by importing `@executablemd/core` - * can decide where a prompt is journaled. - */ -export { useAgentPromptPublisher } from "./src/agent/publication.ts"; -export type { - AgentPromptAssociation, - AgentPromptHandle, - AgentPromptObservation, - AgentPromptPublication, - AgentPromptPublisher, -} from "./src/agent/publication.ts"; - export { TestHarnessError } from "./src/test-harness.ts"; export type { TestHarness, @@ -397,51 +378,6 @@ export type { TestHarnessInstaller, } from "./src/test-harness.ts"; -/** - * The durable Agent Prompt record, for a host that reads a retained journal. - * - * A sealed workflow artifact classifies each Agent session by what its retained - * Prompts say, and the only thing that can answer that is the parser the live - * run already records through. A second reading of the same durable value would - * be a second contract, so the parser and the effect type it belongs to cross - * the boundary instead. - */ -export { AGENT_PROMPT, parsePromptRecord } from "./src/agent/journal.ts"; -export type { PromptRecord } from "./src/agent/journal.ts"; - -/** - * A withheld reply a local person accepted, and the one rule that joins it to - * its turn. - * - * Readers of a held conversation's history — replay, a Sidekick's chat and - * its passive projections — read a withheld turn followed by its acceptance as - * that turn's successful reply. They read it through this reconciler rather - * than their own, so they agree on which acceptances count. - */ -export { - acceptedReplies, - AGENT_PROMPT_REPLY, - parsePromptReply, -} from "./src/agent/reply-acceptance.ts"; -export type { PromptReplyRecord } from "./src/agent/reply-acceptance.ts"; - -/** - * The trusted foreground question about a withheld reply. - * - * Installed by a host with a person in front of it, beside its prompt - * publisher, as one of a held conversation's installations. A host that - * installs none keeps every withheld reply withheld. See - * `src/agent/reply-review.ts`. - */ -export { useAgentReplyReview } from "./src/agent/reply-review.ts"; -export type { - AgentReplyDecision, - AgentReplyFinding, - AgentReplyHold, - AgentReplyReviewer, -} from "./src/agent/reply-review.ts"; -export type { FeedbackSlice } from "./src/agent/reply-review.ts"; - /** * `` as detached configuration, for the host that installs it. * diff --git a/packages/core/mod.ts b/packages/core/mod.ts index 5370ca4bb..41466f802 100644 --- a/packages/core/mod.ts +++ b/packages/core/mod.ts @@ -120,12 +120,6 @@ export type { * the same boundary core's own defaults do. */ export { formDispatcher } from "./src/invocation-identity.ts"; -/** - * The opaque session request a `` element routes. A handler reads its - * descriptive name; only the delivered launch coordinator reads the engine identity. - */ -export { AgentSessionProtocolError, isSessionRequest } from "./src/agent/session-request.ts"; -export type { AgentSessionRequest } from "./src/agent/session-request.ts"; export { ContentError } from "./src/errors.ts"; export { getExpansion } from "./src/expansion.ts"; export type { Expansion } from "./src/expansion.ts"; @@ -237,7 +231,6 @@ export type { SelectedEntry } from "./src/syntax-markdown.ts"; * the selection core's own component reaches. */ export { documentationIndexFor, packageDocumentation } from "./src/component-documentation.ts"; -export { agentDocumentation } from "./src/agent/components.ts"; export type { DocumentationContribution, DocumentationReader, @@ -326,121 +319,6 @@ export { export type { NormalizedIssue } from "./src/validate.ts"; export { validateParsed } from "./src/components/parse-schema.ts"; -// Agent components — // over a provider-factory seam. -export { - AGENT_REGISTRATIONS, - agentIdentityComponents, - installAgentComponents, - useAgentComponents, -} from "./src/agent/components.ts"; -export type { AgentComponentsOptions } from "./src/agent/components.ts"; -export { Agent } from "./src/agent/agent-api.ts"; -// The one deny decision, so a host writing its own permission policy reaches -// the same rule the base handler and every built-in policy reach rather than -// spelling "reject_once, then reject_always, otherwise cancel" again. -export { denyPermission } from "./src/agent/agent-api.ts"; -export type { - AgentApi, - AgentOption, - AgentOptions, - AgentOptionSet, - AgentOptionsRequest, - AgentPromptEvent, - PromptImage, - LaunchOptions, - PermissionMode, - PermissionOption, - PermissionOutcome, - PermissionRequest, - PromptOptions, - Session, - SessionIdentity, - SessionConfiguration, - SessionLaunchResult, -} from "./src/agent/agent-api.ts"; -export { AgentPromptError } from "./src/agent/errors.ts"; -// One authentic use of a conversation. Issuing one is `useConfiguredSession()`, -// which is the only way one comes into being. These accessors read a value — -// whether it claims to be a use, whether this build issued it, which session it -// names and what it says — and refuse a claim nothing issued. Deciding whether -// a use may act stays elsewhere: it belongs to the installation that issued it, -// reached through the coordinator core delivers to the installed provider. -export { - AgentSessionUseError, - claimsConfiguration, - configurationOf, - isSessionUse, - sessionOf, -} from "./src/agent/session-use.ts"; -export type { AgentSessionUse } from "./src/agent/session-use.ts"; -export { useConfiguredSession } from "./src/agent/launch-install.ts"; -// Native session launch — the records one launch retains, and the request its -// public route carries. What runs and retains a phase is not here -// and is not anywhere: it is delivered to the selected provider. -export { AgentLaunchError, sameExecutableBuild } from "./src/agent/launch.ts"; -export type { - DetachedLaunchRecord, - ExecutableBuildBindingV1, - ExitedLaunchRecord, - IdentityProvenance, - InstructionReconciliation, - LaunchFailure, - LaunchFailureClass, - LaunchPhase, - LaunchRecord, - MaterializationPlan, - MaterializationUsage, - MaterializedLaunchRecord, - PreparedLaunchRecord, -} from "./src/agent/launch.ts"; -export { AgentLaunchProtocolError } from "./src/agent/launch-request.ts"; -export type { AgentLaunchRequest } from "./src/agent/launch-request.ts"; -export type { AgentLaunchPhases, AgentLaunchCoordinator } from "./src/agent/launch-coordinator.ts"; -// What a provider reports through the coordinator's optional usage receiver, -// and what a canonical Prompt record retains of it. -export type { - PromptUsage, - PromptUsageReporter, - ReportedTokens, - UsageBuild, - UsageCoverage, - UsageProvenance, - UsageReading, -} from "./src/agent/usage.ts"; -// What settles one session setup. A provider receives the handle through the -// coordinator delivered to its factory; the types are here so it can name them. -export type { - AgentSessionSetup, - AgentSessionSetupState, - ConfigureAgentSession, - ProviderSessionConfiguration, -} from "./src/agent/session-setup.ts"; -// The checkpoint type, because the coordinator's signature names it. The carrier -// itself is exported from nowhere: writing one is reachable only through a -// delivered coordinator, and reading one only from the prompt core is running. -export { AgentPromptCheckpointError } from "./src/agent/checkpoint.ts"; -export type { AgentPromptCheckpoint } from "./src/agent/checkpoint.ts"; -export { launchAgentSession } from "./src/agent/launch-install.ts"; -export { AgentProviders, registerAgentProvider } from "./src/agent/provider-api.ts"; -// `installAgentProvider` is deliberately absent: it takes a launch coordinator, -// and a coordinator reachable by import is one every package and every -// loaded copy can reach. An embedder installs a registered provider through -// `useProviderInstallation()`, which mints one and delivers it privately to the -// factory through this invocation's terminal. -export { useProviderInstallation } from "./src/agent/launch-install.ts"; -export type { - AgentProviderApi, - AgentProviderFactory, - AgentProviderOptions, -} from "./src/agent/provider-api.ts"; -export { - installApproveAll, - installApproveReads, - installAskPermission, - installPermissionMode, - installPromptFailurePolicy, -} from "./src/agent/permission.ts"; - // Shared execution config — the run deadline, the exec and Fetch defaults, and // contextual verbosity, plus the one duration grammar the three timeouts are // written in (re-exported from runtime). diff --git a/packages/core/src/errors.ts b/packages/core/src/errors.ts index 4f1a5f10c..fe8ec6cf5 100644 --- a/packages/core/src/errors.ts +++ b/packages/core/src/errors.ts @@ -408,6 +408,25 @@ function isRecoveredContent(error: object): boolean { return error instanceof ContentError; } +/** + * Whether dismantling an invocation failed anywhere in `error`'s causes. + * + * The same traversal {@link firstCause} makes, answering one question: a + * caller outside core that owns a component invocation tells its own teardown + * failure apart from the work it was tearing down. + */ +export function hasInvocationTeardown(error: unknown): boolean { + return ( + firstCause(error, (cause) => (cause instanceof InvocationTeardownError ? true : undefined)) === + true + ); +} + +/** Whether `cause` itself is `error` or one of its causes, by identity. */ +export function hasCause(error: unknown, cause: unknown): boolean { + return firstCause(error, (candidate) => (candidate === cause ? true : undefined)) === true; +} + /** * The first failure in this one's cause graph that `select` recognises, skipping * whatever `opaque` declares out of scope. diff --git a/packages/core/src/secrets/policy.ts b/packages/core/src/secrets/policy.ts index b8c5abdb4..a57b7cd6f 100644 --- a/packages/core/src/secrets/policy.ts +++ b/packages/core/src/secrets/policy.ts @@ -238,12 +238,14 @@ export function* scanSecrets(content: string): Operation { * answer `false`. Only an execution whose host explicitly disabled detection * clears everything, without a scanner existing to invoke. * - * Package-private, with two callers, both of them bridges out of an - * execution's own source: the output bridge `execute()` owns, and the live - * observation a canonical prompt offers an observing host. Each asks the same - * question — may this leave — about the execution it is running in, which is - * why neither may answer for the other. Exporting it publicly would advertise - * a screen whose answer is worth nothing outside those bridges. + * It has two callers, both of them bridges out of an execution's own source: + * the output bridge `execute()` owns, and the live observation a canonical + * prompt offers an observing host. Each asks the same question — may this + * leave — about the execution it is running in, which is why neither may + * answer for the other. It crosses `./host` only, beside + * {@link retainsOptionalText}, so the Agent package's prompt bridge asks it; + * the root and `./api` omit it, because outside those bridges its answer is + * worth nothing. */ export function* clearsLiveOutput(content: string): Operation { let detection: ExecutionDetection; @@ -273,7 +275,7 @@ export function* clearsLiveOutput(content: string): Operation { * absent or unauthentic binding, a projection that changes the value, a finding * and a scanner that failed all answer `false`. * - * Package-private, like {@link clearsLiveOutput}: it is a question about this + * Host-only, like {@link clearsLiveOutput}: it is a question about this * execution's own optional observations, answered inside that execution. */ export function* retainsOptionalText(value: string): Operation { diff --git a/packages/core/src/secrets/secret-placement.ts b/packages/core/src/secrets/secret-placement.ts index 9285bc506..de3b1e02d 100644 --- a/packages/core/src/secrets/secret-placement.ts +++ b/packages/core/src/secrets/secret-placement.ts @@ -114,6 +114,37 @@ export function encodedOffset(field: Placed | undefined, index: number): number return undefined; } +/** + * Where each approved copy of a string field lands in `rendered`, the exact + * text `JSON.stringify(value, null, indent)` produced for the value holding + * those fields. + * + * Each match keeps its bytes and moves its offsets from the field's own value + * into `rendered`. A copy is kept only where `rendered` holds exactly its + * approved bytes at the projected range; any other copy, and every copy when + * the fields cannot be placed, is dropped rather than approximated. + */ +export function placeApprovedCopies( + rendered: string, + copies: readonly { readonly field: string; readonly match: ApprovedMatch }[], + indent?: number, +): ApprovedMatch[] { + const names = [...new Set(copies.map(({ field }) => field))]; + const placements = place( + `${rendered}\n`, + names.map((name) => [name]), + indent, + ); + return copies.flatMap(({ field, match }) => { + const placement = placements?.[names.indexOf(field)]; + const start = encodedOffset(placement, match.start); + const end = encodedOffset(placement, match.end); + return start === undefined || end === undefined || rendered.slice(start, end) !== match.bytes + ? [] + : [{ ...match, start, end }]; + }); +} + /** Translate one serialized span into a field's own value coordinates. */ export function within( placed: readonly Placed[], diff --git a/packages/core/src/source-owner.ts b/packages/core/src/source-owner.ts index 2fb72d850..554b83bea 100644 --- a/packages/core/src/source-owner.ts +++ b/packages/core/src/source-owner.ts @@ -1,5 +1,6 @@ import type { DurablePosition } from "@executablemd/durable-streams"; import { createContext } from "effection"; +import type { Operation } from "effection"; import type { Json, SourcePosition } from "./types.ts"; import { sourceDescription } from "./source-position.ts"; @@ -17,3 +18,16 @@ export function sourceOwnerDescription( : { "executablemd.source-owner": { coroutineId: owner.coroutineId, index: owner.index } }), }; } + +/** + * The source description for `position`, attributed to the source owner in + * effect where it is read. + * + * Read-only: the Context stays core's own, so a caller describing a durable + * effect names the owner core recorded and cannot install another. + */ +export function* readSourceOwnerDescription( + position: Readonly | undefined, +): Operation> { + return sourceOwnerDescription(position, yield* SourceOwner.get()); +} diff --git a/packages/core/tests/all.test.ts b/packages/core/tests/all.test.ts index f7daffbb3..5c00db102 100644 --- a/packages/core/tests/all.test.ts +++ b/packages/core/tests/all.test.ts @@ -42,9 +42,9 @@ import { Component, retain } from "../src/component-api.ts"; import { getExpansion } from "../src/expansion.ts"; import { retainedSource } from "../src/root-source.ts"; import { registerComponents } from "../src/components/registration.ts"; -import { Agent } from "../src/agent/agent-api.ts"; -import type { AgentPromptEvent } from "../src/agent/agent-api.ts"; -import { agentIdentityComponents, installAgentComponents } from "../src/agent/components.ts"; +import { Agent } from "@executablemd/agent/api"; +import type { AgentPromptEvent } from "@executablemd/agent/api"; +import { agentIdentityComponents, installAgentComponents } from "@executablemd/agent/host"; import { useTempFileCompiler } from "../src/temp-file-compiler.ts"; import { inspectSyntax } from "../src/inspect.ts"; import { RESERVED_STRUCTURAL } from "../src/structural.ts"; diff --git a/packages/core/tests/plugin-api.test.ts b/packages/core/tests/plugin-api.test.ts index cde5907d2..287808ebe 100644 --- a/packages/core/tests/plugin-api.test.ts +++ b/packages/core/tests/plugin-api.test.ts @@ -15,14 +15,13 @@ import type { Operation } from "effection"; import { ActivePlugins, activePlugins, - Agent, Document, document, Plugin, RootMetadata, rootMetadata, } from "../api.ts"; -import type { AgentOptions, DocumentApi, Session, SessionConfiguration } from "../api.ts"; +import type { DocumentApi } from "../api.ts"; // The placeholder text is canonical core's own, not part of what a Plugin // imports: a wrapper receives it from `next()` rather than naming it. import { DOCUMENT_PLACEHOLDER } from "../src/plugin-apis.ts"; @@ -223,61 +222,3 @@ describe("PA3 — ActivePlugins is an ordered immutable snapshot", () => { expect(snapshot).not.toBe(installed); }); }); - -/** - * PA4 — the Agent Api a Plugin composes agent work through. - * - * A Plugin depends on `@executablemd/core/api` and nothing else, so what it can - * reach about a session is settled here: the Api itself, the choices an agent - * advertises, and the configuration a `` authored — all in Core's own - * vocabulary. Whatever protocol the installed provider speaks does not appear. - */ -describe("PA4 — the Agent Api composes from the Plugin entrypoint", () => { - it("wraps options() and a configured session() the ordinary way", function* () { - const seen: unknown[][] = []; - const choices: AgentOptions = { - agent: "codex", - model: { - selected: "gpt-5.4", - options: [ - { - id: "gpt-5.4", - name: "GPT-5.4", - description: "the current one", - group: { id: "frontier", name: "Frontier" }, - }, - ], - }, - effort: null, - }; - - const composed = yield* scoped(function* (): Operation<[Session, AgentOptions]> { - yield* Agent.around( - { - // deno-lint-ignore require-yield - *session(args): Operation { - seen.push([...args]); - return { sessionKey: "plugin:review", cwd: "/repo" }; - }, - // deno-lint-ignore require-yield - *options(): Operation { - return choices; - }, - }, - { at: "min" }, - ); - yield* Agent.around({ - *session(args, next): Operation { - return yield* next(...args); - }, - }); - return [yield* Agent.operations.session("review"), yield* Agent.operations.options("codex")]; - }); - - // The request, and nothing else: no settings object travels this route. - expect(seen).toEqual([["review"]]); - expect(composed[0]).toEqual({ sessionKey: "plugin:review", cwd: "/repo" }); - expect(composed[1].model?.options[0]?.group).toEqual({ id: "frontier", name: "Frontier" }); - expect(composed[1].effort).toBe(null); - }); -}); diff --git a/packages/core/tests/syntax-catalog.test.ts b/packages/core/tests/syntax-catalog.test.ts index 98775ca18..c43ceea81 100644 --- a/packages/core/tests/syntax-catalog.test.ts +++ b/packages/core/tests/syntax-catalog.test.ts @@ -26,8 +26,6 @@ import { API } from "@executablemd/runtime"; import type { DirectoryEntry, LinkStatResult, StatResult } from "@executablemd/runtime"; import { repositoryComponentName } from "../src/components/candidates.ts"; import { - AGENT_REGISTRATIONS, - agentIdentityComponents, CORE_COMPONENT_NAMES, inspectComponent, inspectSyntax, @@ -37,6 +35,7 @@ import { RESERVED_STRUCTURAL, STRUCTURAL_DECLARATIONS, } from "../mod.ts"; +import { AGENT_REGISTRATIONS, agentIdentityComponents } from "@executablemd/agent/host"; import type { CompleteComponentSyntaxEntry, InstalledStructuralSyntaxEntry, diff --git a/packages/core/tests/try-catch-finally-harness.ts b/packages/core/tests/try-catch-finally-harness.ts index afb3f78d0..c50bf27cc 100644 --- a/packages/core/tests/try-catch-finally-harness.ts +++ b/packages/core/tests/try-catch-finally-harness.ts @@ -10,11 +10,9 @@ import { executeInstalled } from "../host.ts"; import type { HostExecution } from "../host.ts"; import { recordedFiles, useRecordedFiles } from "./support/fragment-files.ts"; import { useNormalizedOutput } from "../src/output/normalize.ts"; -import { Agent } from "../src/agent/agent-api.ts"; -import type { AgentPromptEvent, Session } from "../src/agent/agent-api.ts"; -import { isSessionRequest } from "../src/agent/session-request.ts"; -import { installAgentComponents, agentIdentityComponents } from "../src/agent/components.ts"; -import { AgentPromptError } from "../src/agent/errors.ts"; +import { Agent, AgentPromptError, isSessionRequest } from "@executablemd/agent/api"; +import type { AgentPromptEvent, Session } from "@executablemd/agent/api"; +import { agentIdentityComponents, installAgentComponents } from "@executablemd/agent/host"; export function fixture(name: string): Operation { return readTextFile( diff --git a/packages/test-agent/package.json b/packages/test-agent/package.json index 595ed1b3f..e988856f1 100644 --- a/packages/test-agent/package.json +++ b/packages/test-agent/package.json @@ -12,6 +12,7 @@ "@effectionx/scope-eval": "0.1.3", "@effectionx/stream-helpers": "0.8.3", "@executablemd/acp": "workspace:*", + "@executablemd/agent": "workspace:*", "@executablemd/core": "workspace:*", "@executablemd/durable-streams": "workspace:*", "@executablemd/runtime": "workspace:*", diff --git a/packages/test-agent/src/child-configuration.ts b/packages/test-agent/src/child-configuration.ts index b107ee8e8..6b8603496 100644 --- a/packages/test-agent/src/child-configuration.ts +++ b/packages/test-agent/src/child-configuration.ts @@ -32,11 +32,14 @@ */ import type { Operation } from "effection"; -import { hasContent, registerAgentProvider, tryContent } from "@executablemd/core"; -import type { AgentComponentsOptions, AgentProviderOptions, Json } from "@executablemd/core"; +import { hasContent, tryContent } from "@executablemd/core"; +import { registerAgentProvider } from "@executablemd/agent/api"; +import type { Json } from "@executablemd/core"; +import type { AgentProviderOptions } from "@executablemd/agent/api"; +import type { AgentComponentsOptions } from "@executablemd/agent/host"; import { createPartitionedAcpxProvider } from "@executablemd/acp"; import type { AcpxProviderDependencies } from "@executablemd/acp"; -import { installInvocationAgentProvider } from "@executablemd/core/host"; +import { installInvocationAgentProvider } from "@executablemd/agent/host"; import { installControlledLauncher } from "@executablemd/runtime"; import type { ChildDeclaration, diff --git a/packages/test-agent/src/components.ts b/packages/test-agent/src/components.ts index a76c644d4..87fd11d0b 100644 --- a/packages/test-agent/src/components.ts +++ b/packages/test-agent/src/components.ts @@ -18,16 +18,9 @@ import { createContext, Err, Ok, spawn, suspend, useScope, withResolvers } from import type { Operation, Result, Scope } from "effection"; import { basename, dirname, isAbsolute, resolve } from "node:path"; import type { EvalScope } from "@effectionx/scope-eval"; -import { - Component, - installPromptFailurePolicy, - getExpansion, - raise, - registerAgentProvider, - registerComponents, - tryContent, - useProviderInstallation, -} from "@executablemd/core"; +import { Component, getExpansion, raise, registerComponents, tryContent } from "@executablemd/core"; +import { registerAgentProvider } from "@executablemd/agent/api"; +import { installPromptFailurePolicy, useProviderInstallation } from "@executablemd/agent/host"; import type { ErrorSegment, Json, PropsSchema, Segment } from "@executablemd/core"; import { createMemorySessionRouteStore, createPartitionedAcpxProvider } from "@executablemd/acp"; import type { diff --git a/packages/test-agent/tests/command-lazy.test.ts b/packages/test-agent/tests/command-lazy.test.ts index 488750888..e0189b6cf 100644 --- a/packages/test-agent/tests/command-lazy.test.ts +++ b/packages/test-agent/tests/command-lazy.test.ts @@ -14,7 +14,8 @@ import * as os from "node:os"; import * as path from "node:path"; import { ensureDir, rm, writeTextFile } from "@effectionx/fs"; import { API } from "@executablemd/runtime"; -import { execute, installAgentComponents, useTempFileCompiler } from "@executablemd/core"; +import { execute, useTempFileCompiler } from "@executablemd/core"; +import { installAgentComponents } from "@executablemd/agent/host"; import { InMemoryStream } from "@executablemd/durable-streams"; import { useTesting } from "@executablemd/testing"; import type { TestResult } from "@executablemd/testing"; diff --git a/packages/test-agent/tests/components.test.ts b/packages/test-agent/tests/components.test.ts index 88a2874fb..263375092 100644 --- a/packages/test-agent/tests/components.test.ts +++ b/packages/test-agent/tests/components.test.ts @@ -15,13 +15,8 @@ import { ensureDir, rm, writeTextFile } from "@effectionx/fs"; import { randomUUID } from "node:crypto"; import * as path from "node:path"; import * as os from "node:os"; -import { - agentIdentityComponents, - Component, - Elicitation, - installAgentComponents, - parseTemplate, -} from "@executablemd/core"; +import { Component, Elicitation, parseTemplate } from "@executablemd/core"; +import { agentIdentityComponents, installAgentComponents } from "@executablemd/agent/host"; import { installAnswerProvider } from "@executablemd/core/host"; import type { AnswerConfiguration } from "@executablemd/core/host"; import { executeInstalled } from "@executablemd/core/host"; diff --git a/packages/test-agent/tests/cross-package-resolution.test.ts b/packages/test-agent/tests/cross-package-resolution.test.ts index e22391e60..ec3243bc3 100644 --- a/packages/test-agent/tests/cross-package-resolution.test.ts +++ b/packages/test-agent/tests/cross-package-resolution.test.ts @@ -26,14 +26,13 @@ import { tmpdir } from "node:os"; import { dirname, join } from "node:path"; import { InMemoryStream } from "@executablemd/durable-streams"; import { - agentIdentityComponents, collect, Component, execute, inspectComponent, - installAgentComponents, useTempFileCompiler, } from "@executablemd/core"; +import { agentIdentityComponents, installAgentComponents } from "@executablemd/agent/host"; import type { ComponentInfo } from "@executablemd/core"; import { installTestingComponents } from "@executablemd/testing"; import { installTestAgentComponents } from "../src/components.ts"; diff --git a/packages/test-agent/tests/native-launch.test.ts b/packages/test-agent/tests/native-launch.test.ts index 7de7c8a2d..c8b1c64fa 100644 --- a/packages/test-agent/tests/native-launch.test.ts +++ b/packages/test-agent/tests/native-launch.test.ts @@ -16,14 +16,15 @@ */ import { beforeAll, describe, it } from "@executablemd/test-support/bdd"; import { expect } from "@executablemd/test-support/expect"; -import { agentIdentityComponents, useTempFileCompiler } from "@executablemd/core"; +import { useTempFileCompiler } from "@executablemd/core"; +import { agentIdentityComponents } from "@executablemd/agent/host"; import { ensure, scoped } from "effection"; import type { Operation, Result } from "effection"; import { ensureDir, rm, writeTextFile } from "@effectionx/fs"; import { randomUUID } from "node:crypto"; import * as path from "node:path"; import * as os from "node:os"; -import { installAgentComponents } from "@executablemd/core"; +import { installAgentComponents } from "@executablemd/agent/host"; import { executeInstalled } from "@executablemd/core/host"; import type { Json } from "@executablemd/core"; import { API, installControlledLauncher, useHostFiles } from "@executablemd/runtime"; diff --git a/packages/test-agent/tests/provider.test.ts b/packages/test-agent/tests/provider.test.ts index 69cc1e7e8..a832610c1 100644 --- a/packages/test-agent/tests/provider.test.ts +++ b/packages/test-agent/tests/provider.test.ts @@ -7,7 +7,7 @@ import { describe, it } from "@executablemd/test-support/bdd"; import { expect } from "@executablemd/test-support/expect"; import { scoped, sleep, spawn, withResolvers, useScope, until } from "effection"; import type { Operation } from "effection"; -import { Agent } from "@executablemd/core"; +import { Agent } from "@executablemd/agent/api"; import { createAcpRuntime } from "@executablemd/acp"; import type { AcpRuntimeHandle, AcpRuntimeOptions, SessionRouteContext } from "@executablemd/acp"; import { tmpdir } from "node:os"; diff --git a/packages/test-agent/tests/session-configuration.test.ts b/packages/test-agent/tests/session-configuration.test.ts index dd2f8bc15..77a0961b4 100644 --- a/packages/test-agent/tests/session-configuration.test.ts +++ b/packages/test-agent/tests/session-configuration.test.ts @@ -4,13 +4,8 @@ import { expect } from "@executablemd/test-support/expect"; import { scoped } from "effection"; import type { Operation, Result } from "effection"; import * as path from "node:path"; -import { - agentIdentityComponents, - content, - registerComponents, - inlineSource, - installAgentComponents, -} from "@executablemd/core"; +import { content, registerComponents, inlineSource } from "@executablemd/core"; +import { agentIdentityComponents, installAgentComponents } from "@executablemd/agent/host"; import { installAnswerProvider } from "@executablemd/core/host"; import type { ExecutionInstallation } from "@executablemd/core/host"; import { forEach } from "@effectionx/stream-helpers"; diff --git a/packages/test-agent/tests/smoke.test.ts b/packages/test-agent/tests/smoke.test.ts index 86780eb7d..282d3f466 100644 --- a/packages/test-agent/tests/smoke.test.ts +++ b/packages/test-agent/tests/smoke.test.ts @@ -11,12 +11,8 @@ import { expect } from "@executablemd/test-support/expect"; import { scoped } from "effection"; import type { Operation, Result } from "effection"; import * as path from "node:path"; -import { - agentIdentityComponents, - execute, - inlineSource, - installAgentComponents, -} from "@executablemd/core"; +import { execute, inlineSource } from "@executablemd/core"; +import { agentIdentityComponents, installAgentComponents } from "@executablemd/agent/host"; import { installAnswerProvider } from "@executablemd/core/host"; import type { ExecutionInstallation } from "@executablemd/core/host"; import { forEach } from "@effectionx/stream-helpers"; diff --git a/packages/testing/tests/agent-composition.test.ts b/packages/testing/tests/agent-composition.test.ts index 11fd99cf6..619824762 100644 --- a/packages/testing/tests/agent-composition.test.ts +++ b/packages/testing/tests/agent-composition.test.ts @@ -14,10 +14,12 @@ import { ensureDir, rm, writeTextFile } from "@effectionx/fs"; import { randomUUID } from "node:crypto"; import * as path from "node:path"; import * as os from "node:os"; -import { agentIdentityComponents } from "@executablemd/core"; +import { agentIdentityComponents } from "@executablemd/agent/host"; import { executeInstalled } from "@executablemd/core/host"; -import { Agent, execute, installAgentComponents } from "@executablemd/core"; -import type { AgentPromptEvent, PromptOptions, Session } from "@executablemd/core"; +import { execute } from "@executablemd/core"; +import { Agent } from "@executablemd/agent/api"; +import { installAgentComponents } from "@executablemd/agent/host"; +import type { AgentPromptEvent, PromptOptions, Session } from "@executablemd/agent/api"; import { installTestingComponents } from "../mod.ts"; import type { Json } from "@executablemd/core"; diff --git a/packages/workflow/package.json b/packages/workflow/package.json index 245fb6af3..08c55fbba 100644 --- a/packages/workflow/package.json +++ b/packages/workflow/package.json @@ -10,6 +10,7 @@ "dependencies": { "@effectionx/context-api": "0.6.0", "@effectionx/fs": "0.3.0", + "@executablemd/agent": "workspace:*", "@executablemd/core": "workspace:*", "@executablemd/durable-streams": "workspace:*", "@executablemd/runtime": "workspace:*", diff --git a/packages/workflow/src/deno/agent-publication.ts b/packages/workflow/src/deno/agent-publication.ts index 44b31f866..faa24e528 100644 --- a/packages/workflow/src/deno/agent-publication.ts +++ b/packages/workflow/src/deno/agent-publication.ts @@ -29,7 +29,7 @@ */ import type { Operation } from "effection"; -import type { AgentPromptPublication, AgentPromptPublisher } from "@executablemd/core/host"; +import type { AgentPromptPublication, AgentPromptPublisher } from "@executablemd/agent/host"; import type { WorkflowRunDatabase } from "../storage/api.ts"; import { WorkflowTransactionError } from "../storage/errors.ts"; import { withEnlistedJournalRoute } from "./journal-route.ts"; diff --git a/packages/workflow/src/deno/artifact/records.ts b/packages/workflow/src/deno/artifact/records.ts index 272174880..507492f51 100644 --- a/packages/workflow/src/deno/artifact/records.ts +++ b/packages/workflow/src/deno/artifact/records.ts @@ -28,8 +28,8 @@ import { Buffer } from "node:buffer"; import type { Operation } from "effection"; import { prepareElicitation, validateParsed } from "@executablemd/core"; -import { AGENT_PROMPT, parsePromptRecord } from "@executablemd/core/host"; -import type { PromptRecord } from "@executablemd/core/host"; +import { AGENT_PROMPT, parsePromptRecord } from "@executablemd/agent/host"; +import type { PromptRecord } from "@executablemd/agent/host"; import { parseDurableEvent } from "@executablemd/durable-streams"; import type { DurableEvent, EffectDescription, Json, Result } from "@executablemd/durable-streams"; import { SUSPENSION_ANSWER } from "../../suspension/answer.ts"; diff --git a/packages/workflow/tests/workflow-agent-checkpoints.test.ts b/packages/workflow/tests/workflow-agent-checkpoints.test.ts index 30965c84c..b6d6b553c 100644 --- a/packages/workflow/tests/workflow-agent-checkpoints.test.ts +++ b/packages/workflow/tests/workflow-agent-checkpoints.test.ts @@ -16,23 +16,20 @@ import { describe, it } from "@executablemd/test-support/bdd"; import { expect } from "@executablemd/test-support/expect"; -import { executeInstalled, parsePromptRecord } from "@executablemd/core/host"; -import { useAgentPromptPublisher } from "@executablemd/core/host"; -import { - Agent, - agentIdentityComponents, - collect, - inlineSource, - installAgentComponents, -} from "@executablemd/core"; +import { executeInstalled } from "@executablemd/core/host"; +import { parsePromptRecord } from "@executablemd/agent/host"; +import { useAgentPromptPublisher } from "@executablemd/agent/host"; +import { collect, inlineSource } from "@executablemd/core"; +import { Agent } from "@executablemd/agent/api"; +import { agentIdentityComponents, installAgentComponents } from "@executablemd/agent/host"; +import type { Json } from "@executablemd/core"; import type { AgentPromptEvent, AgentLaunchCoordinator, AgentProviderFactory, - Json, PromptUsage, Session, -} from "@executablemd/core"; +} from "@executablemd/agent/api"; import type { DurableEvent } from "@executablemd/durable-streams"; import { readFile } from "node:fs/promises"; import { DatabaseSync } from "node:sqlite"; diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 620d6b2cf..07009e830 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -102,6 +102,9 @@ importers: '@executablemd/acp': specifier: workspace:* version: link:packages/acp + '@executablemd/agent': + specifier: workspace:* + version: link:packages/agent '@executablemd/cli': specifier: workspace:* version: link:packages/cli @@ -168,6 +171,9 @@ importers: '@agentclientprotocol/sdk': specifier: 1.9.0 version: 1.9.0(zod@4.6.7) + '@executablemd/agent': + specifier: workspace:* + version: link:../agent '@executablemd/core': specifier: workspace:* version: link:../core @@ -187,6 +193,27 @@ importers: specifier: 4.6.7 version: 4.6.7 + packages/agent: + dependencies: + '@effectionx/context-api': + specifier: 0.6.0 + version: 0.6.0(effection@4.1.0) + '@executablemd/core': + specifier: workspace:* + version: link:../core + '@executablemd/durable-streams': + specifier: workspace:* + version: link:../durable-streams + '@executablemd/runtime': + specifier: workspace:* + version: link:../runtime + effection: + specifier: 4.1.0 + version: 4.1.0 + zod: + specifier: ^4.3.6 + version: 4.6.7 + packages/cli: dependencies: '@agentclientprotocol/sdk': @@ -198,6 +225,9 @@ importers: '@executablemd/acp': specifier: workspace:* version: link:../acp + '@executablemd/agent': + specifier: workspace:* + version: link:../agent '@executablemd/core': specifier: workspace:* version: link:../core @@ -399,6 +429,9 @@ importers: '@executablemd/acp': specifier: workspace:* version: link:../acp + '@executablemd/agent': + specifier: workspace:* + version: link:../agent '@executablemd/core': specifier: workspace:* version: link:../core @@ -541,6 +574,9 @@ importers: '@effectionx/fs': specifier: 0.3.0 version: 0.3.0(effection@4.1.0) + '@executablemd/agent': + specifier: workspace:* + version: link:../agent '@executablemd/core': specifier: workspace:* version: link:../core diff --git a/scripts/build-npm.ts b/scripts/build-npm.ts index 554e89e77..b813202d4 100644 --- a/scripts/build-npm.ts +++ b/scripts/build-npm.ts @@ -79,7 +79,6 @@ function* packagedDocuments(pkgDir: URL): Operation { // what declares an asset shipped. for (const relative of [ "src/components/components.md", - "src/agent/components.md", "src/components.md", "src/composition/components.md", ]) { diff --git a/scripts/lib/compile.ts b/scripts/lib/compile.ts index 28c7d6875..fc5abdf38 100644 --- a/scripts/lib/compile.ts +++ b/scripts/lib/compile.ts @@ -66,7 +66,7 @@ export const PACKAGED_DOCUMENTS = ["packages/cli/src/documents"]; */ export const PACKAGED_DOCUMENTATION = [ "packages/core/src/components/components.md", - "packages/core/src/agent/components.md", + "packages/agent/src/components.md", "packages/cli/src/components.md", "packages/testing/src/components.md", "packages/web/src/components.md", diff --git a/scripts/runtime-test-exclusions.ts b/scripts/runtime-test-exclusions.ts index c577ba00c..634090a0e 100644 --- a/scripts/runtime-test-exclusions.ts +++ b/scripts/runtime-test-exclusions.ts @@ -206,11 +206,17 @@ const DENO_ONLY_TOOLING: RuntimeExclusion[] = [ { path: "packages/acp/tests/loaded-copy.test.ts", reason: - "builds the second copy of core's session setup machinery with `deno bundle`, which is Deno's, and drives the real ACP provider against it; the classification it proves — a resolved Session is recognized by its public data and everything else is handed to the delivered coordinator — is runtime-neutral and the same dispatch is exercised on every runtime by packages/acp/tests/provider.test.ts", + "builds the second copy of the Agent package's session setup machinery with `deno bundle`, which is Deno's, and drives the real ACP provider against it; the classification it proves — a resolved Session is recognized by its public data and everything else is handed to the delivered coordinator — is runtime-neutral and the same dispatch is exercised on every runtime by packages/acp/tests/provider.test.ts", issue: DERIVED_SCOPE, }, { - path: "packages/core/tests/agent-session-use-loaded-copy.test.ts", + path: "packages/agent/tests/package-graph.test.ts", + reason: + "reads each public Core entry's resolved module graph through `deno info --json`, which is Deno's resolver; the namespace, manifest and Core-only execution halves of the same boundary run under all three in package-boundary.test.ts", + issue: DERIVED_SCOPE, + }, + { + path: "packages/agent/tests/agent-session-use-loaded-copy.test.ts", reason: "builds the second copy of the Session-use module with `deno bundle`, which is Deno's; the refusal it proves — a claim without this copy's authority answers nothing — is runtime-neutral and is also covered for rebuilt, copied and foreign-installation values by agent-session-use.test.ts under all three", issue: DERIVED_SCOPE, diff --git a/scripts/smoke-documentation.ts b/scripts/smoke-documentation.ts index e27298fa1..6ba944065 100644 --- a/scripts/smoke-documentation.ts +++ b/scripts/smoke-documentation.ts @@ -97,6 +97,29 @@ main(function* (args) { return; } + // The Agent components are documented by a second asset, the Agent + // package's own, and their metadata still names the origin they kept. A + // binary that embedded core's documentation and not that one documents + // `` and fails here. + const prompt = yield* ask(binary, ["syntax", "Prompt", "--include", include], elsewhere); + if (prompt.code !== 0) { + yield* fail( + prompt.stderr.includes(MISSING_ASSET) + ? `the binary carries no Agent documentation: ${prompt.stderr.trim()}` + : `xmd syntax Prompt exited ${prompt.code}: ${prompt.stderr.trim()}`, + ); + return; + } + const missingPrompt = absent(prompt.stdout, [ + "### ``", + "**Origin:** `@executablemd/core`", + "Sends a prompt and renders the reply", + ]); + if (missingPrompt.length > 0) { + yield* fail(`xmd syntax Prompt rendered no ${JSON.stringify(missingPrompt)}`); + return; + } + const typo = yield* ask(binary, ["syntax", "TemdDir", "--include", include], elsewhere); if (typo.code === 0) { yield* fail("xmd syntax TemdDir succeeded, so the name lookup admits anything"); diff --git a/scripts/smoke-prompt-usage.ts b/scripts/smoke-prompt-usage.ts index 5bc73d683..3b831e8ba 100644 --- a/scripts/smoke-prompt-usage.ts +++ b/scripts/smoke-prompt-usage.ts @@ -17,7 +17,7 @@ import { randomUUID } from "node:crypto"; import { tmpdir } from "node:os"; import * as path from "node:path"; import process from "node:process"; -import { parsePromptRecord } from "@executablemd/core/host"; +import { parsePromptRecord } from "@executablemd/agent/host"; const BINARY = path.join(process.cwd(), "dist", "xmd"); const FAKE_CLAUDE = path.join(process.cwd(), "packages/acp/tests/fixtures/fake-claude-cli.cjs"); diff --git a/scripts/tests/cli-npm-bin.test.ts b/scripts/tests/cli-npm-bin.test.ts index c1ac2d49e..02a98ffce 100644 --- a/scripts/tests/cli-npm-bin.test.ts +++ b/scripts/tests/cli-npm-bin.test.ts @@ -725,9 +725,9 @@ describe("npm CLI package", { sanitizeOps: false, sanitizeResources: false }, () // The documentation assets travel with the package, and the emitted binary // resolves them from its own tree rather than from a checkout. `Prompt` - // lives in core's *agent* boundary rather than in its own `components.md`, - // so this exercises a second copied asset path: a build that copied only - // the first would still answer for core's own components and fail here. + // is documented by the Agent package's own `components.md` rather than + // core's, so this exercises a second copied asset path: a build that copied + // only core's would still answer for core's own components and fail here. const documented = yield* runEmittedBinIn(root, elsewhere, ["syntax", "Prompt"]); expect(documented.code).toBe(0); expect(documented.stdout).toContain("### ``"); diff --git a/scripts/tests/jsr-consumer-documentation.test.ts b/scripts/tests/jsr-consumer-documentation.test.ts index 1072c5257..cceedaaf7 100644 --- a/scripts/tests/jsr-consumer-documentation.test.ts +++ b/scripts/tests/jsr-consumer-documentation.test.ts @@ -32,12 +32,13 @@ import { z } from "npm:zod@^4"; const ROOT = fileURLToPath(new URL("../../", import.meta.url)); const TIMEOUT = 180_000; -/** The workspace members a consumer of core has to resolve. */ -const MEMBERS = ["core", "runtime", "durable-streams", "acp"] as const; +/** The workspace members a consumer of core and the Agent package has to resolve. */ +const MEMBERS = ["core", "agent", "runtime", "durable-streams", "acp"] as const; -/** Every documentation asset the product ships, by package-relative path. */ +/** Every documentation asset the product ships, by package and package-relative path. */ const ASSETS: Record = { - core: ["src/components/components.md", "src/agent/components.md"], + core: ["src/components/components.md"], + agent: ["src/components.md"], }; /** A package manifest, only as far as this needs it. */ @@ -85,11 +86,15 @@ describe("Tier SYN — a staged JSR consumer", () => { // 1. The publish filter selects the assets. This is the payload claim, and // it is checked against the real `deno publish` selection rather than // against a directory listing. - const selected = yield* publishedFiles("core"); - expect(selected.length).toBeGreaterThan(0); - for (const asset of ASSETS.core ?? []) { - const expected = path.join(ROOT, "packages/core", asset); - expect([asset, selected.includes(expected)]).toEqual([asset, true]); + const selected: Record = {}; + for (const [pkg, assets] of Object.entries(ASSETS)) { + const files = yield* publishedFiles(pkg); + expect(files.length).toBeGreaterThan(0); + for (const asset of assets) { + const expected = path.join(ROOT, "packages", pkg, asset); + expect([pkg, asset, files.includes(expected)]).toEqual([pkg, asset, true]); + } + selected[pkg] = files; } const staged = yield* until(mkdtemp(path.join(tmpdir(), "xmd-jsr-consumer-"))); @@ -104,7 +109,7 @@ describe("Tier SYN — a staged JSR consumer", () => { for (const member of MEMBERS) { const from = path.join(ROOT, "packages", member); const to = path.join(staged, member); - const files = member === "core" ? selected : yield* publishedFiles(member); + const files = selected[member] ?? (yield* publishedFiles(member)); for (const file of files) { const relative = path.relative(from, file); if (relative.startsWith("..")) { @@ -119,9 +124,11 @@ describe("Tier SYN — a staged JSR consumer", () => { // Every asset is in the staged tree because publish selected it, not // because a copy swept the directory. - for (const asset of ASSETS.core ?? []) { - const stagedAsset = path.join(staging.core ?? "", asset); - expect([asset, yield* exists(stagedAsset)]).toEqual([asset, true]); + for (const [pkg, assets] of Object.entries(ASSETS)) { + for (const asset of assets) { + const stagedAsset = path.join(staging[pkg] ?? "", asset); + expect([pkg, asset, yield* exists(stagedAsset)]).toEqual([pkg, asset, true]); + } } // 3. A consumer outside the repository, resolving the staged packages @@ -135,11 +142,12 @@ describe("Tier SYN — a staged JSR consumer", () => { path.join(consumer, "main.ts"), [ "// The public surface, assembled the way a consumer would: core's own", - "// registrations plus its Agent boundary, so the document can name a", - "// component from each of the two documentation assets. One call brings", - "// the Agent registrations and the documentation that describes them,", - "// which is the whole point of the bootstrap being one thing.", - 'import { collect, useAgentComponents } from "@executablemd/core";', + "// registrations plus the Agent package's host boundary, so the document", + "// can name a component from each of the two documentation assets. One", + "// call brings the Agent registrations and the documentation that", + "// describes them, which is the whole point of the bootstrap being one thing.", + 'import { collect } from "@executablemd/core";', + 'import { useAgentComponents } from "@executablemd/agent/host";', "// The host boundary is its own entrypoint, and a consumer reaches it", "// the same way: `@executablemd/core/host`.", 'import { executeInstalled } from "@executablemd/core/host";', diff --git a/scripts/tests/packaged-document.test.ts b/scripts/tests/packaged-document.test.ts index f891d3fa1..64a064838 100644 --- a/scripts/tests/packaged-document.test.ts +++ b/scripts/tests/packaged-document.test.ts @@ -86,9 +86,9 @@ function* packagedDocuments(): Operation { * Every `components.md` under a package's `src/`, at whatever depth it sits. * * Depth is the reason this is a walk rather than a per-package guess: core - * ships two, one beneath `src/components/` and one beneath `src/agent/`, - * because documentation lives beside the registration boundary it documents - * rather than at a fixed path. + * ships one beneath `src/components/`, the Agent package one directly in + * `src/` and git one beneath `src/composition/`, because documentation lives + * beside the registration boundary it documents rather than at a fixed path. */ function* packagedDocumentation(): Operation { const found: string[] = []; diff --git a/specs/acp-client-spec.md b/specs/acp-client-spec.md index e4becb8da..020300fb9 100644 --- a/specs/acp-client-spec.md +++ b/specs/acp-client-spec.md @@ -1,10 +1,19 @@ # Executable.md ACP Client The `Agent` Api, the Agent / Session / Prompt components, prompt journaling and -replay, the provider-factory seam, and the `Config` timeouts are implemented in -`@executablemd/core`. A provider is supplied through the `rootProvider` factory -seam (§The provider-factory seam). This specification owns the public operations, -configuration and retained record shapes. +replay, and the provider-factory seam are implemented in `@executablemd/agent`, +over the execution `@executablemd/core` owns; the `Config` timeouts are +`@executablemd/runtime`'s (§Config). The Agent package has two entries. +`@executablemd/agent/api` carries the `Agent` Api, `AgentConversationProvider`, +`AgentProviders`, the Session accessors and the contracts a Plugin or a provider +is written in. `@executablemd/agent/host` carries what a host installs and +reads back: the components, permission and failure policies, provider +installation, held conversations, reply review, Prompt publication and the +retained Prompt and reply readers. Core by itself registers no Agent component; +a host that installs this package's components supplies them. A provider is +supplied through the `rootProvider` factory seam (§The provider-factory seam). +This specification owns the public operations, configuration and retained +record shapes. [Agent permissions and generated work](./workflow-workspace-spec.md#8-agents-inspect-xmd-mutates) own workflow isolation and mapping publication; [native Agent sessions](./native-agent-session-launch-spec.md#ownership-and-concurrency) own the shared @@ -38,8 +47,8 @@ second statement of the rules. ## Components: the document surface -`installAgentComponents()` registers six components for the installing scope -(executable-mdx-spec §5.3): AgentProvider, Agent, Session.Launch, Prompt, +`installAgentComponents()` from `@executablemd/agent/host` registers six +components for the installing scope (executable-mdx-spec §5.3): AgentProvider, Agent, Session.Launch, Prompt, ApproveAll and AskPermission. Session is the seventh agent word and is supplied separately, because its implementation names durable work after its own invocation: a host declares it to the execution through the identity-bearing @@ -55,6 +64,11 @@ projection and invocation lifetime exactly as for any other `.ts` component. Props take string and boolean values, from a literal or from an expression that resolves to one. +All seven, and the documentation that describes them, name the component +origin `@executablemd/core`. They kept it when they moved from Core into the +Agent package, because an origin is part of how canonical resolution, a +retained journal and a documentation lookup identify a component. + A canonical Markdown test may configure one nested `host="run"` execution with a direct TestAgent declaration (testing-spec.md). That declaration carries only detached scenario data. The trusted child host installs the controlled root @@ -126,7 +140,7 @@ invocation boundary runs after the component has returned. ## The Agent Api -`Agent` is an Effection Api (`@executablemd/core`) for stateful coding-agent +`Agent` is an Effection Api (`@executablemd/agent/api`) for stateful coding-agent sessions, distinct from the stateless Sample Api. It has exactly six contextual operations: @@ -311,8 +325,8 @@ call and carries no permission to construct, own or answer. ## Confirmed Session information Read `Session.identity` to record which conversation performed work without -opening provider-private storage. Core exports `SessionIdentity` beside -`Session` from `@executablemd/core/api` and its root type surface: +opening provider-private storage. The Agent package exports `SessionIdentity` +beside `Session` from `@executablemd/agent/api`: ```ts interface SessionIdentity { @@ -629,7 +643,7 @@ interface AgentConversationProvider { A provider that serves saved conversations installs an `AgentConversationProvider` in its own provider scope, through the Context of -that same name on `@executablemd/core/api`, alongside whatever `Agent` +that same name on `@executablemd/agent/api`, alongside whatever `Agent` middleware it provides. The factory signature is unchanged. The object carries no coordinator, permission flag, configuration approval, history mapping or completion receipt: it is trusted behavior a conversation selects, and @@ -849,7 +863,7 @@ Session and Prompt are written inside an expansion, with an element to name the session and a journal already around them. A host that discusses something with an agent has neither: a person is typing into a chat, the history outlives the process, and there is no document. `useAgentConversation()` on -`@executablemd/core/host` is that conversation, and it is the genuine one — a +`@executablemd/agent/host` is that conversation, and it is the genuine one — a canonical agent session, journaled turns, verified configuration, and an identity the provider reattaches to. @@ -959,9 +973,12 @@ native identity, which only a turn's own canonical record establishes. coordinator are installed inside `Execution.document`, and a durable preparation precedes both, so a conversation opened there could reach neither. The conversation is a host-declared identity component in a synthetic root Core -owns: canonical resolution selects it, hands its implementation the execution's +executes: canonical resolution selects it, hands its implementation the execution's claimant, and the session is placed under the engine's own identity for that -invocation. The `id` names the history and nothing else — it carries no +invocation. The root's source is `` at the synthetic +path `agent/conversation.md`, and the component registers under the origin +`@executablemd/core`; a retained history is admitted against that source, +so it is unchanged from when Core shipped the conversation. The `id` names the history and nothing else — it carries no claimant, establishes no native identity and overrides none. **Its root is never completed.** A durable root that records its terminal diff --git a/specs/executable-mdx-spec.md b/specs/executable-mdx-spec.md index b7e4cc2cd..1eb1c3679 100644 --- a/specs/executable-mdx-spec.md +++ b/specs/executable-mdx-spec.md @@ -2109,7 +2109,7 @@ the read that asked for it rather than appearing in it. | `src/generated-root-owner.ts` | `createGeneratedRootOwner()`, `isGeneratedRootEvent()`, `HostExecutionError`, `BoundRootEvaluator` — the live owner of one execution's explicit root evaluations. It allocates each evaluation a durable sequence of its own past every evaluation the retained history holds, partitions it from the document's continuation through Core-owned views of one journal, and holds the bound operation a trusted handle exposes. The operation refuses rather than waits where the execution ended without activating the runner, and an authoritative failure one evaluation raised becomes the execution's own outcome rather than being raised into the document's scope | | `src/generated-xmd-preview.ts` | `previewGeneratedXmdRoot()`, `GeneratedXmdRootPreview`, `GeneratedXmdPreviewError` — projecting settled literal `` text a response prefix already says, including direct nested Output and withholding executable ancestors (§6.9). It takes the whole accumulated prefix and returns `Result` directly rather than an `Operation`, because it performs no suspended work: no file is read, no name resolved, no component invoked, no expression evaluated, no admission granted and no history written. A prefix still arriving is a success stating `incomplete`, and source the language does not allow where it is written is an `Err` — told apart by the scan's own report of the constructs it began and could not finish. Only settled meaning projects: an expression, an interpolation and a nested component wait, and a passive fence is the literal example it looks like | | `src/generated-interpolation.ts` | `readsBinding()` — the one rule deciding whether a piece of text would read a binding, shared by admission, which refuses such text in a fragment, and by the prefix preview, which leaves it out. Text one of them called literal and the other called a read would be two readings of one rule | -| `src/agent/conversation.ts` | `useAgentConversation()`, `AgentConversation`, `AgentConversationRequest`, `AgentConversationError`, `AgentReplyWithheldError` — one retained agent conversation a trusted host holds open over the history stream it supplies, under the installations it captured through `executeInstalled()`. A host-declared identity component in a synthetic root core owns, because a provider and its placement coordinator are installed inside `Execution.document`; the session is placed under the engine's own claimant-issued identity and the host's conversation id names the history alone. The element serves turns and does not return, so the root records no terminal and reopening resumes a partial continuation. Each turn is one journaled Prompt under its own durable name, run in a task of its own, reaching the same `runPrompt()` the component does rather than a copy. `evaluateGeneratedXmdRoot()` is a third job on the same mailbox, sharing its admission guard and cancellation-join protocol: the element obtains the actual method on its own execution's handle through a private readiness bridge before announcing the conversation ready, and an evaluation sends no provider prompt, changes no configuration, and runs on a durable sequence distinct from the conversation's turns | +| `packages/agent/src/conversation.ts` | `useAgentConversation()`, `AgentConversation`, `AgentConversationRequest`, `AgentConversationError`, `AgentReplyWithheldError` — one retained agent conversation a trusted host holds open over the history stream it supplies, under the installations it captured through `executeInstalled()`. A host-declared identity component in a synthetic root core owns, because a provider and its placement coordinator are installed inside `Execution.document`; the session is placed under the engine's own claimant-issued identity and the host's conversation id names the history alone. The element serves turns and does not return, so the root records no terminal and reopening resumes a partial continuation. Each turn is one journaled Prompt under its own durable name, run in a task of its own, reaching the same `runPrompt()` the component does rather than a copy. `evaluateGeneratedXmdRoot()` is a third job on the same mailbox, sharing its admission guard and cancellation-join protocol: the element obtains the actual method on its own execution's handle through a private readiness bridge before announcing the conversation ready, and an evaluation sends no provider prompt, changes no configuration, and runs on a durable sequence distinct from the conversation's turns | | `src/invocation.ts` | `withInvocation()`, `Invocation`, `InvocationTeardownError` — the component invocation boundary (§4.4) | | `src/expansion.ts` | `Expansion`, `getExpansion()` — what an executable element knows about its own expansion (§5.6) | | `src/invocation-identity.ts` | `ComponentInvocation`, `IdentityComponent`, `IdentityClaimant`, `ImportSelection`, `installIdentities()`, `issueInvocation()`, `ComponentInvocationError` — what a trusted host declares to an execution, the domains that execution mints for it, and the one-use issuance a claimant answers for (§5.6) | @@ -2149,10 +2149,10 @@ the read that asked for it rather than appearing in it. | `packages/workflow/src/deno/workspace/host.ts` | `withWorkflowWorkspace()` — the run's effect coordinator, logical cwd `/`, and Files provider installed together inside one execution | | `src/generated-xmd-preview.ts` | `previewGeneratedXmdRoot()`, `GeneratedXmdRootPreview`, `GeneratedXmdPreviewError` — projecting settled literal `` text a response prefix already says, including direct nested Output and withholding executable ancestors (§6.9). It takes the whole accumulated prefix and returns `Result` directly rather than an `Operation`, because it performs no suspended work: no file is read, no name resolved, no component invoked, no expression evaluated, no admission granted and no history written. A prefix still arriving is a success stating `incomplete`, and source the language does not allow where it is written is an `Err` — told apart by the scan's own report of the constructs it began and could not finish, through the same walk that decides what a fence, a quoted `>`, an inline code span and a tag-like expression are. Only settled meaning projects: an expression, an interpolation and a nested component wait, and a passive fence is the literal example it looks like | | `src/generated-interpolation.ts` | `readsBinding()` — the one rule deciding whether a piece of text would read a binding, shared by admission, which refuses such text, and by the prefix preview, which leaves it out. Text one of them called literal and the other called a read would be two readings of one rule | -| `src/agent/publication.ts` | `useAgentPromptPublisher()`, `AgentPromptPublisher`, `AgentPromptPublication`, `AgentPromptObservation`, `AgentPromptHandle`, `AgentPromptAssociation` — where a trusted host retains something beside a canonical Prompt, and is shown that Prompt while it is still talking. `begin()` is called before the provider is asked and its opaque return is carried back on `publish()`, which appends the record inside whatever transaction the host opened; the optional `observe()` is offered the whole source received so far, already cleared for disclosure by the execution the turn runs in, after each delta and once more when the stream returns text the deltas did not say. An observation is a snapshot and not an account: no session, checkpoint, turn number or append, `null` withdraws the body for the rest of that turn, and an empty string is a cleared prefix that says nothing. A publisher that observes must also begin, refused where it is installed; a publisher with no `observe` accumulates no prefix and is scanned for nothing. A host that raises from either call has failed a trusted operation, so the run's durability failure is activated with its own error and no record claims the turn — never an agent failure | -| `src/agent/conversation.ts` | `useAgentConversation()`, `AgentConversation`, `AgentConversationRequest`, `AgentConversationError`, `AgentReplyWithheldError` — one agent conversation a trusted host holds open over the history stream it supplies, under the installations it captured through `executeInstalled()`. A host-declared identity component in a synthetic root core owns, because a provider and its launch coordinator are installed inside `Execution.document` and a durable preparation precedes both; the session is therefore placed under the engine's own claimant-issued identity and the host's conversation id names the history alone. The element serves turns and does not return, so the root records no terminal and reopening resumes a partial continuation. Each turn is one journaled Prompt under its own durable name, run in a task of its own, reaching the same `runPrompt()` the component does rather than a copy. Every operation of the conversation goes to the one `AgentConversationProvider` its host installed, read once from Context in the element's own scope after installation and before readiness — so a handler cannot forward a request's name past the setup that carries the configuration requirement, nor replace a prompt's session after one was checked, and a provider that installs no object refuses the opening before the conversation is bound rather than falling back to routing. The conversation's agent is resolved through that provider before the turn's session is resolved and is then stated to both of the turn's operations, so the session and the prompt are the same agent's while the request itself still carries no agent. The conversation keeps private evidence of the exact `Session` settling its own request produced, and refuses one it never settled or one substituted afterwards before asking for a prompt stream. `evaluateGeneratedXmdRoot()` is a third job on the same mailbox, sharing its admission guard and cancellation-join protocol: the element obtains the actual method on its own execution's handle through a private readiness bridge before announcing the conversation ready, and an evaluation sends no provider prompt, changes no configuration, and runs on a durable sequence distinct from the conversation's turns. A failure of the run that a caller caught is raised again by the release that ends the conversation, because a root that records no terminal leaves no completion for it to travel through. The first turn's activation commits one `agent_conversation_configuration` record — the provider, the resolved command and the complete active provider configuration — before any native work may begin; a later activation parses what the provider builds under today and writes nothing, so a changed adapter command or configuration continues the same native conversation, and a reopening re-offers that record in its own position so the turns written after it replay in order. Each turn's setup carries snapshots of the history's native assertion and of where its provider state is: the initial record's provider and command with the latest nonempty Prompt `sessionKey` | -| `src/agent/conversation-provider.ts` | `AgentConversationProvider` — one name for the interface and the Context, exported from `@executablemd/core/api`, carrying the four operations a retained conversation does its work through: `agent()`, `session()` for the genuine opaque request under an explicit agent, `options()` and a cold `prompt()` for the exact Session the conversation supplies. A provider that serves saved conversations installs one in its own provider scope beside whatever `Agent` middleware it provides; the factory signature is unchanged and the object carries no coordinator, permission flag, configuration approval, history mapping or completion receipt. Selection is read once per conversation and is an ordinary local afterwards, so a later selection cannot reach an open chat; the object's lifetime is its provider's, and a method called after that provider's teardown refuses. Undefined is the default and an answer: ordinary `Agent` middleware alone does not serve conversations | -| `src/agent/provider-configuration.ts` | `ProviderSessionConfiguration`, `AdmitProviderConfiguration`, `parseProviderConfiguration()`, `freezeJson()` — what an installed provider says it is constructing a session under, held as values rather than a digest. All four members are required and absence is never a default, so a provider that cannot state one states none; the values are parsed into Core's own copy and frozen. It imports no transport type: the MCP connection shapes and permission spellings are the provider's vocabulary, validated by the provider and stored as JSON | +| `packages/agent/src/publication.ts` | `useAgentPromptPublisher()`, `AgentPromptPublisher`, `AgentPromptPublication`, `AgentPromptObservation`, `AgentPromptHandle`, `AgentPromptAssociation` — where a trusted host retains something beside a canonical Prompt, and is shown that Prompt while it is still talking. `begin()` is called before the provider is asked and its opaque return is carried back on `publish()`, which appends the record inside whatever transaction the host opened; the optional `observe()` is offered the whole source received so far, already cleared for disclosure by the execution the turn runs in, after each delta and once more when the stream returns text the deltas did not say. An observation is a snapshot and not an account: no session, checkpoint, turn number or append, `null` withdraws the body for the rest of that turn, and an empty string is a cleared prefix that says nothing. A publisher that observes must also begin, refused where it is installed; a publisher with no `observe` accumulates no prefix and is scanned for nothing. A host that raises from either call has failed a trusted operation, so the run's durability failure is activated with its own error and no record claims the turn — never an agent failure | +| `packages/agent/src/conversation.ts` | `useAgentConversation()`, `AgentConversation`, `AgentConversationRequest`, `AgentConversationError`, `AgentReplyWithheldError` — one agent conversation a trusted host holds open over the history stream it supplies, under the installations it captured through `executeInstalled()`. A host-declared identity component in a synthetic root core owns, because a provider and its launch coordinator are installed inside `Execution.document` and a durable preparation precedes both; the session is therefore placed under the engine's own claimant-issued identity and the host's conversation id names the history alone. The element serves turns and does not return, so the root records no terminal and reopening resumes a partial continuation. Each turn is one journaled Prompt under its own durable name, run in a task of its own, reaching the same `runPrompt()` the component does rather than a copy. Every operation of the conversation goes to the one `AgentConversationProvider` its host installed, read once from Context in the element's own scope after installation and before readiness — so a handler cannot forward a request's name past the setup that carries the configuration requirement, nor replace a prompt's session after one was checked, and a provider that installs no object refuses the opening before the conversation is bound rather than falling back to routing. The conversation's agent is resolved through that provider before the turn's session is resolved and is then stated to both of the turn's operations, so the session and the prompt are the same agent's while the request itself still carries no agent. The conversation keeps private evidence of the exact `Session` settling its own request produced, and refuses one it never settled or one substituted afterwards before asking for a prompt stream. `evaluateGeneratedXmdRoot()` is a third job on the same mailbox, sharing its admission guard and cancellation-join protocol: the element obtains the actual method on its own execution's handle through a private readiness bridge before announcing the conversation ready, and an evaluation sends no provider prompt, changes no configuration, and runs on a durable sequence distinct from the conversation's turns. A failure of the run that a caller caught is raised again by the release that ends the conversation, because a root that records no terminal leaves no completion for it to travel through. The first turn's activation commits one `agent_conversation_configuration` record — the provider, the resolved command and the complete active provider configuration — before any native work may begin; a later activation parses what the provider builds under today and writes nothing, so a changed adapter command or configuration continues the same native conversation, and a reopening re-offers that record in its own position so the turns written after it replay in order. Each turn's setup carries snapshots of the history's native assertion and of where its provider state is: the initial record's provider and command with the latest nonempty Prompt `sessionKey` | +| `packages/agent/src/conversation-provider.ts` | `AgentConversationProvider` — one name for the interface and the Context, exported from `@executablemd/agent/api`, carrying the four operations a retained conversation does its work through: `agent()`, `session()` for the genuine opaque request under an explicit agent, `options()` and a cold `prompt()` for the exact Session the conversation supplies. A provider that serves saved conversations installs one in its own provider scope beside whatever `Agent` middleware it provides; the factory signature is unchanged and the object carries no coordinator, permission flag, configuration approval, history mapping or completion receipt. Selection is read once per conversation and is an ordinary local afterwards, so a later selection cannot reach an open chat; the object's lifetime is its provider's, and a method called after that provider's teardown refuses. Undefined is the default and an answer: ordinary `Agent` middleware alone does not serve conversations | +| `packages/agent/src/provider-configuration.ts` | `ProviderSessionConfiguration`, `AdmitProviderConfiguration`, `parseProviderConfiguration()`, `freezeJson()` — what an installed provider says it is constructing a session under, held as values rather than a digest. All four members are required and absence is never a default, so a provider that cannot state one states none; the values are parsed into Core's own copy and frozen. It imports no transport type: the MCP connection shapes and permission spellings are the provider's vocabulary, validated by the provider and stored as JSON | | `packages/workflow/src/generated-observations.ts` | `evaluateGeneratedFragment()` — the workflow policy adapter over `evaluateGeneratedXmd()`, returning its rendered text directly as `Operation`; `GeneratedObservation` remains the read-table entry type, not an output envelope | | `packages/workflow/src/journal.ts` | the `workflow_run` record, canonical-record recognition, and the refusals that name differing fields without their values | | `packages/workflow/src/run.ts` | `retainedWorkflowInstallation()` and `getWorkflowRun()` — associating one execution with a run already created, as the `ExecutionInstallation` a trusted host passes to `executeInstalled()`, contributing a mandatory run-identity admission and the `prepare` hook that reopens the run inside the durable root. The association resolves no revision and imports no Git feature, and a run retains the bytes it executes, so nothing afterwards reaches a repository for its Markdown | @@ -11267,6 +11267,12 @@ stand. The acceptance uses no new turn ordinal. Replay restores the pair without recovering a live approval or contacting a provider. +The conversation, its reply review and the acceptance record belong to +`@executablemd/agent/host` (`useAgentConversation()`, `useAgentReplyReview()`, +`AGENT_PROMPT_REPLY`). The scanner, the journal gate and the one-use append +approvals stay Core's: the conversation runs its execution through +`executeInstalledWithApprovals()` from `@executablemd/core/host`. + The same execution scans the complete serialization at each append. Its one-use exception applies to the acceptance's text field, the same Send's generated admission for the accepted source and approved byte ranges whose diff --git a/tsconfig.node.json b/tsconfig.node.json index 194545022..26f97d196 100644 --- a/tsconfig.node.json +++ b/tsconfig.node.json @@ -17,6 +17,8 @@ "@executablemd/core/host/node": ["./packages/core/component-modules/node.ts"], "@executablemd/core/host/bun": ["./packages/core/component-modules/bun.ts"], "@executablemd/acp": ["./packages/acp/mod.ts"], + "@executablemd/agent/api": ["./packages/agent/api.ts"], + "@executablemd/agent/host": ["./packages/agent/host.ts"], "@executablemd/cli": ["./packages/cli/src/cli.ts"], "@executablemd/cli/api": ["./packages/cli/api.ts"], "@executablemd/core": ["./packages/core/mod.ts"], @@ -37,6 +39,7 @@ }, "include": [ "packages/acp/**/*.ts", + "packages/agent/**/*.ts", "packages/cli/**/*.ts", "packages/core/**/*.ts", "packages/durable-streams/**/*.ts", From 7deb51732b9570fb52aa754849d18a9ba3ff4ef9 Mon Sep 17 00:00:00 2001 From: Taras Mankovski Date: Sun, 15 Nov 2026 15:05:32 -0500 Subject: [PATCH 4/6] Import Agent from its package in generated test Plugins The nested-run inspection host built its Plugin source with Agent imported from Core's root, which no longer exports it. The documentation smoke's closing line now names both packages it documents. Co-Authored-By: Claude Opus 5.5 --- packages/cli/tests/testing-execution-host.test.ts | 4 +++- scripts/smoke-documentation.ts | 2 +- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/packages/cli/tests/testing-execution-host.test.ts b/packages/cli/tests/testing-execution-host.test.ts index 79f5539f9..ba94dcbf4 100644 --- a/packages/cli/tests/testing-execution-host.test.ts +++ b/packages/cli/tests/testing-execution-host.test.ts @@ -591,11 +591,13 @@ const INSPECTION_PROBE = doc( function inspectionHost(observe = false): string { const core = new URL("../../core/mod.ts", import.meta.url).href; const api = new URL("../../core/api.ts", import.meta.url).href; + const agent = new URL("../../agent/api.ts", import.meta.url).href; const testing = new URL("../../testing/mod.ts", import.meta.url).href; const runtime = new URL("../../runtime/mod.ts", import.meta.url).href; const install = cliRuntime() === "deno" ? "useDataUriCompiler" : "useTempFileCompiler"; return doc( - `import { Agent, registerComponents, ${install} } from ${JSON.stringify(core)};`, + `import { registerComponents, ${install} } from ${JSON.stringify(core)};`, + `import { Agent } from ${JSON.stringify(agent)};`, `import { writeTextFile } from ${JSON.stringify(runtime)};`, 'import { fileURLToPath } from "node:url";', 'const trace = fileURLToPath(new URL("./inspection-events.json", import.meta.url));', diff --git a/scripts/smoke-documentation.ts b/scripts/smoke-documentation.ts index 6ba944065..96c7dacff 100644 --- a/scripts/smoke-documentation.ts +++ b/scripts/smoke-documentation.ts @@ -162,7 +162,7 @@ main(function* (args) { } console.log( - "documentation smoke: one component documented, an unknown one refused, two rendered " + + "documentation smoke: core's and the Agent package's components documented, an unknown one refused, two rendered " + "from a directory that is not the checkout", ); }); From 560323c3b3565cfb9e48845cc8318ea04ec9f54b Mon Sep 17 00:00:00 2001 From: Taras Mankovski Date: Sun, 15 Nov 2026 15:16:26 -0500 Subject: [PATCH 5/6] Name the Agent documentation probe in the release specification Co-Authored-By: Claude Opus 5.5 --- specs/release-process-spec.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/specs/release-process-spec.md b/specs/release-process-spec.md index 0a6e97a30..d3ff532ab 100644 --- a/specs/release-process-spec.md +++ b/specs/release-process-spec.md @@ -776,6 +776,9 @@ the checkout and with a component search path of its own, so neither the working directory nor `--include` can answer for the product's own documentation: - `xmd syntax TempDir` renders the registry metadata *and* the long-form prose; +- `xmd syntax Prompt` does the same from the Agent package's own + `components.md`, a second asset, with the `@executablemd/core` origin its + components keep; - `xmd syntax TemdDir` reaches the ordinary unknown-name refusal with empty stdout — the half that makes the probe evidence, because a binary missing its assets fails both lookups the same way, so a passing first case alone would From f6966db47c97510164850dfe27037e7e86aee193 Mon Sep 17 00:00:00 2001 From: Taras Mankovski Date: Sun, 15 Nov 2026 15:31:24 -0500 Subject: [PATCH 6/6] Prove the Agent npm entrypoints and name Agent's ownership in the specs PB1 now reads `deno info` through the scoped quiet-process pattern, so a passing run no longer forwards megabytes of graph JSON, and its one predicate covers the registry spellings (npm, JSR and jsr.io) beside the local Agent paths. The npm CLI artifact suite asserts the emitted Core manifest has no Agent dependency and that a consumer outside the checkout imports both Agent subpaths through the emitted export map. The release specification records Agent's publish order, its relocated documentation asset and the new npm check. The language spec states the documentation join by registered origin and why Agent keeps the Core origin; the ACP and launch specs name the Agent package as the owner of configured uses, setup snapshots and the delivered launch coordinator, with phases retained under Core-issued invocation identity. Co-Authored-By: Claude Opus 5.5 --- packages/agent/tests/package-graph.test.ts | 124 ++++++++++++++++----- scripts/tests/cli-npm-bin.test.ts | 63 +++++++++++ specs/acp-client-spec.md | 61 +++++----- specs/executable-mdx-spec.md | 18 ++- specs/native-agent-session-launch-spec.md | 26 +++-- specs/release-process-spec.md | 15 ++- 6 files changed, 229 insertions(+), 78 deletions(-) diff --git a/packages/agent/tests/package-graph.test.ts b/packages/agent/tests/package-graph.test.ts index a73aff92f..7ad034fcd 100644 --- a/packages/agent/tests/package-graph.test.ts +++ b/packages/agent/tests/package-graph.test.ts @@ -8,8 +8,9 @@ */ import { describe, it } from "@executablemd/test-support/bdd"; import { expect } from "@executablemd/test-support/expect"; +import { scoped } from "effection"; import type { Operation } from "effection"; -import { exec } from "@effectionx/process"; +import { exec, useQuietProcessOutput } from "@executablemd/runtime"; import * as path from "node:path"; import process from "node:process"; import { fileURLToPath, pathToFileURL } from "node:url"; @@ -18,6 +19,15 @@ const REPOSITORY = fileURLToPath(new URL("../../../", import.meta.url)); const AGENT_PACKAGE = pathToFileURL(path.join(REPOSITORY, "packages/agent/")).href; const OLD_AGENT_SOURCE = pathToFileURL(path.join(REPOSITORY, "packages/core/src/agent/")).href; +/** + * The Agent package as a registry resolves it: a bare or `npm:`/`jsr:` name, + * resolved npm and JSR package ids, and a jsr.io module URL. A Core entry that + * imported a published Agent instead of the workspace copy reaches no local + * path, so the local prefixes alone would pass it. + */ +const REGISTRY_AGENT = /^(?:(?:npm|jsr):\/?)?@executablemd\/agent(?:$|[@/])/; +const JSR_AGENT_MODULE = "https://jsr.io/@executablemd/agent/"; + /** Every public Core entry, by manifest subpath. */ const CORE_ENTRIES = [ "mod.ts", @@ -28,52 +38,108 @@ const CORE_ENTRIES = [ "component-modules/bun.ts", ]; -/** The modules one entry's resolved graph contains, failing on any graph error. */ -function* graphOf(entry: string): Operation { - const info = yield* exec(process.execPath, { - arguments: ["info", "--json", "--frozen", "--node-modules-dir=none", entry], - cwd: REPOSITORY, - }).join(); - if (info.code !== 0) { +function record(value: unknown): Record { + return typeof value === "object" && value !== null ? Object(value) : {}; +} + +/** + * Everything one entry's resolved graph names, failing on any graph error. + * + * Module specifiers, the requested specifiers of their dependencies, redirects + * in both directions and the resolved npm and JSR package ids — each place a + * registry spelling of the Agent package could appear. + */ +function* graphOf(entry: string): Operation<{ modules: string[]; names: string[] }> { + // `deno info --json` prints megabytes for one graph; the answer is parsed + // here, and a passing run has nothing to show. + const info = yield* scoped(function* () { + yield* useQuietProcessOutput(); + return yield* exec({ + command: [process.execPath, "info", "--json", "--frozen", "--node-modules-dir=none", entry], + cwd: REPOSITORY, + }); + }); + if (info.exitCode !== 0) { throw new Error(`deno info failed for ${entry}:\n${info.stderr}`); } - const parsed: unknown = JSON.parse(info.stdout); - const modules = - typeof parsed === "object" && parsed !== null ? Reflect.get(parsed, "modules") : undefined; - if (!Array.isArray(modules) || modules.length === 0) { + const parsed = record(JSON.parse(info.stdout)); + const listed = parsed.modules; + if (!Array.isArray(listed) || listed.length === 0) { throw new Error(`deno info reported no modules for ${entry}`); } - const specifiers: string[] = []; - for (const module of modules) { - const specifier: unknown = Reflect.get(module, "specifier"); - const error: unknown = Reflect.get(module, "error"); - if (error !== undefined) { - throw new Error(`${entry} has a graph error at ${String(specifier)}: ${String(error)}`); + const modules: string[] = []; + const names: string[] = []; + for (const one of listed) { + const module = record(one); + if (module.error !== undefined) { + throw new Error( + `${entry} has a graph error at ${String(module.specifier)}: ${String(module.error)}`, + ); + } + if (typeof module.specifier === "string") { + modules.push(module.specifier); } - if (typeof specifier === "string") { - specifiers.push(specifier); + for (const dependency of Array.isArray(module.dependencies) ? module.dependencies : []) { + const requested = record(dependency).specifier; + if (typeof requested === "string") { + names.push(requested); + } } } - return specifiers; + for (const [from, to] of Object.entries(record(parsed.redirects))) { + names.push(from, String(to)); + } + for (const [requested, resolved] of Object.entries(record(parsed.packages))) { + names.push(requested, String(resolved)); + } + names.push(...Object.keys(record(parsed.npmPackages))); + return { modules, names: [...modules, ...names] }; } -function agentModules(specifiers: readonly string[]): string[] { - return specifiers.filter( - (specifier) => specifier.startsWith(AGENT_PACKAGE) || specifier.startsWith(OLD_AGENT_SOURCE), +function namesAgent(name: string): boolean { + return ( + name.startsWith(AGENT_PACKAGE) || + name.startsWith(OLD_AGENT_SOURCE) || + name.startsWith(JSR_AGENT_MODULE) || + REGISTRY_AGENT.test(name) ); } describe("Tier PB — Core resolves no Agent package", () => { it("PB1: no public Core entry's module graph reaches the Agent package", function* () { + // The registry spellings no workspace graph contains, so the predicate the + // graph rows rely on is checked against them directly. + for (const spelling of [ + "@executablemd/agent", + "@executablemd/agent/api", + "npm:@executablemd/agent@0.14.1/host", + "npm:/@executablemd/agent@0.14.1/esm/api.js", + "@executablemd/agent@0.14.1", + "jsr:@executablemd/agent@^0.14.1/api", + "jsr:/@executablemd/agent@0.14.1/host", + "https://jsr.io/@executablemd/agent/0.14.1/api.ts", + ]) { + expect([spelling, namesAgent(spelling)]).toEqual([spelling, true]); + } + for (const unrelated of [ + "@executablemd/agentic", + "npm:/@executablemd/core@0.14.1/esm/mod.js", + "https://jsr.io/@executablemd/core/0.14.1/mod.ts", + ]) { + expect([unrelated, namesAgent(unrelated)]).toEqual([unrelated, false]); + } + for (const entry of CORE_ENTRIES) { - const modules = yield* graphOf(path.join("packages/core", entry)); - expect([entry, agentModules(modules)]).toEqual([entry, []]); + const graph = yield* graphOf(path.join("packages/core", entry)); + expect([entry, graph.names.filter(namesAgent)]).toEqual([entry, []]); } // The positive control: the same probe sees the Agent package, and Core // beneath it, where they are actually in the graph. const agent = yield* graphOf("packages/agent/host.ts"); - expect(agentModules(agent)).toContain(`${AGENT_PACKAGE}src/components.ts`); - expect(agent).toContain(pathToFileURL(path.join(REPOSITORY, "packages/core/mod.ts")).href); - expect(agentModules(agent).some((one) => one.startsWith(OLD_AGENT_SOURCE))).toBe(false); + expect(agent.names.filter(namesAgent)).toContain(`${AGENT_PACKAGE}src/components.ts`); + expect(agent.modules).toContain( + pathToFileURL(path.join(REPOSITORY, "packages/core/mod.ts")).href, + ); + expect(agent.modules.some((one) => one.startsWith(OLD_AGENT_SOURCE))).toBe(false); }); }); diff --git a/scripts/tests/cli-npm-bin.test.ts b/scripts/tests/cli-npm-bin.test.ts index 02a98ffce..e36d65e69 100644 --- a/scripts/tests/cli-npm-bin.test.ts +++ b/scripts/tests/cli-npm-bin.test.ts @@ -16,6 +16,8 @@ import { expect } from "@executablemd/test-support/expect"; import { runShell, shellQuote } from "@executablemd/test-support/launch"; import { ensure, scoped, until } from "effection"; import { createApi } from "@effectionx/context-api"; +import * as sourceAgentApi from "@executablemd/agent/api"; +import * as sourceAgentHost from "@executablemd/agent/host"; import * as sourceGitApi from "@executablemd/git/api"; import { ensureDir, exists, readdir, readTextFile, writeTextFile } from "@effectionx/fs"; import { createHash } from "node:crypto"; @@ -453,6 +455,67 @@ describe("npm CLI package", { sanitizeOps: false, sanitizeResources: false }, () }); }); + /** + * The Agent package as npm consumers receive it, and Core without it. + * + * The dependency points one way: Core's emitted manifest names no Agent + * dependency, so a Core-only installation carries no Agent code. The Agent + * artifact publishes both of its entrypoints, which a Node consumer outside + * the checkout reaches by package name through the emitted export map — the + * route a Plugin or a host takes, and the one a Deno run cannot exercise + * because the workspace answers for it. + */ + it("publishes the Agent package's /api and /host and keeps Agent out of Core", function* () { + const { root } = builtPackage(); + + const core: Manifest & Record = JSON.parse( + yield* readTextFile(path.join(root, "packages/core/npm/package.json")), + ); + const coreDependencies = [ + "dependencies", + "peerDependencies", + "optionalDependencies", + "devDependencies", + ].flatMap((field) => Object.keys(Object(core[field] ?? {}))); + // The positive control: a manifest that lost its dependencies would have + // no Agent entry by having no entries. + expect(coreDependencies).toContain("@executablemd/runtime"); + expect(coreDependencies.filter((name) => name.startsWith("@executablemd/agent"))).toEqual([]); + + const agent: Manifest & { name?: string; exports?: Record } = JSON.parse( + yield* readTextFile(path.join(root, "packages/agent/npm/package.json")), + ); + expect(agent.name).toBe("@executablemd/agent"); + expect(Object.keys(agent.exports ?? {}).toSorted()).toEqual(["./api", "./host"]); + + const consumer = yield* useTempDirectory("xmd-npm-agent-consumer-"); + yield* until( + symlink( + path.join(root, PKG_DIR, "npm/node_modules"), + path.join(consumer, "node_modules"), + "dir", + ), + ); + const probe = path.join(consumer, "agent-entries.mjs"); + yield* writeTextFile( + probe, + [ + 'const api = await import("@executablemd/agent/api");', + 'const host = await import("@executablemd/agent/host");', + "console.log(JSON.stringify({ api: Object.keys(api).toSorted(), host: Object.keys(host).toSorted() }));", + ].join("\n"), + ); + const loaded = yield* exec("node", { arguments: [probe], cwd: consumer }).join(); + expect({ code: loaded.code, stderr: loaded.stderr }).toMatchObject({ code: 0 }); + const emitted: { api: string[]; host: string[] } = JSON.parse(loaded.stdout); + expect(emitted.api).toContain("Agent"); + expect(emitted.host).toContain("installAgentComponents"); + expect(emitted).toEqual({ + api: Object.keys(sourceAgentApi).toSorted(), + host: Object.keys(sourceAgentHost).toSorted(), + }); + }); + /** * A program piped into the emitted bin, through a pipe that really closes. * diff --git a/specs/acp-client-spec.md b/specs/acp-client-spec.md index 020300fb9..51d4df217 100644 --- a/specs/acp-client-spec.md +++ b/specs/acp-client-spec.md @@ -29,8 +29,8 @@ second statement of the rules. - **Agent** — a resolvable agent name (a string, an ACP agent command). Resolution and defaults: §The Agent Api. - **Session** — the value naming one conversation: - `{ sessionKey; cwd; agentSessionId?; readonly identity? }`. Issued by the installed provider; a configured use is Core-issued. §Sessions: ownership, routes and attachment. -- **Configured use** — `AgentSessionUse`, a Core-issued opaque carrier of one + `{ sessionKey; cwd; agentSessionId?; readonly identity? }`. Issued by the installed provider; a configured use is Agent-issued. §Sessions: ownership, routes and attachment. +- **Configured use** — `AgentSessionUse`, an Agent-issued opaque carrier of one configured use of a conversation. §Session configuration. - **Turn** — one journaled prompt: one subscription of the cold stream `prompt()` returns. §The Agent Api, §Journaling and replay. @@ -340,7 +340,7 @@ association. ACPX reports `acpx.agentSessionId` for an asserted native identity, otherwise `acpx.acpSessionId` for the confirmed ACP loading target. Values keep the provider's exact opaque spelling. Native assertion takes precedence when both exist; `agentSessionId` remains native-only. Other -providers may omit the property and Core defines no closed kind catalog. +providers may omit the property and the Agent package defines no closed kind catalog. Each read observes the latest confirmation for that exact Session. Its returned pair is frozen: `const saved = session.identity` keeps that reading even if the @@ -358,7 +358,7 @@ declare `agentIdentityComponents()`, and execute an Agent element named Prompt. Ordinary `Agent.around` middleware can retain the resolved Session before the first Prompt. At that Prompt's actual `started` event, the same configured use exposes confirmation and verified settings, including when the -installing Core is a separate loaded copy: +installing Agent package is a separate loaded copy: ```ts const saved = session.identity; @@ -399,9 +399,9 @@ model the conversation is already on. Configuration is not an `Agent.session()` argument. Session middleware receives only a name or opaque request and returns the Session selected by its final -route. The request's Core-private issuance carries its frozen configuration; +route. The request's Agent-private issuance carries its frozen configuration; only the coordinator delivered directly to the provider factory can read that -issuance and complete it with the provider's exact Session. Core issues a +issuance and complete it with the provider's exact Session. The Agent package issues a configured use only from that completion. `request.with({ name })` keeps the same issuance and configuration. @@ -420,11 +420,11 @@ that request, and closes it in `finally`. The result is an `AgentSessionUse` only when the final route finished a configured request; middleware may instead select an unconfigured route. -`AgentSessionUse` is an opaque nominal subtype of `Session`: one Core-issued +`AgentSessionUse` is an opaque nominal subtype of `Session`: one Agent-issued configured use of a conversation, carrying the exact provider Session that -finished the final opaque request and its configuration in Core-owned identity +finished the final opaque request and its configuration in Agent-owned identity state. One configured Session element issues one use and selects that same -object for its nested operations. Core freezes the carrier and its copied +object for its nested operations. The Agent package freezes the carrier and its copied configuration; it does not copy or freeze the provider Session. `sessionOf()`, `configurationOf()` and `isSessionUse()` inspect an authentic value. No public operation wraps an existing Session with arbitrary settings, so a structural @@ -438,7 +438,7 @@ use. A first `started` event keeps that final routed configured use rather than substituting its raw provider Session to expose confirmation. The settings travel inside that frozen use when a prompt or launch names the -conversation. Only Core and the installed provider can read them — a spread, a +conversation. Only the Agent package and the installed provider can read them — a spread, a descriptor copy, the real Session presented as configured, or a use from another installation or loaded copy refuses rather than being treated as configured. Middleware may inspect, delegate or replace the whole Session. The @@ -519,8 +519,8 @@ is written back through the existing replay, and the steps above verify it. Repeated operations under an unchanged selection therefore add no model write, while a genuine change is written once and verified before the next prompt. -The configured-session carrier is issued by Core after `session()` resolves an -exact value registered by the installed provider. A Core-owned +The configured-session carrier is issued by the Agent package after `session()` resolves an +exact value registered by the installed provider. An Agent-owned resolve-and-issue operation supplies the programmatic path; middleware can inspect, delegate or reroute the resulting use but cannot mint or rebuild one. The private context used by Session only selects the enclosing lexical use for @@ -577,8 +577,9 @@ nothing". ## The provider-factory seam A provider is a factory that installs `Agent` middleware for its scope, and — -if it serves saved conversations — one provider object for them. Core delivers -its coordinator directly to the factory; it never travels through Agent +if it serves saved conversations — one provider object for them. The Agent package +delivers its coordinator directly to the factory, beside the component invocation +identity Core issues each element,; it never travels through Agent middleware: ```ts @@ -647,7 +648,7 @@ that same name on `@executablemd/agent/api`, alongside whatever `Agent` middleware it provides. The factory signature is unchanged. The object carries no coordinator, permission flag, configuration approval, history mapping or completion receipt: it is trusted behavior a conversation selects, and -everything it is held to stays with Core. How a held turn routes through it is +everything it is held to stays with the Agent package. How a held turn routes through it is owned by §A conversation a trusted host holds open. Each of the four operations takes explicitly what the public chain supplied @@ -690,7 +691,7 @@ historical coordinates, never a command to execute — and the latest nonempty `sessionKey` its Prompt records name. Both are `undefined` for an ordinary setup and for a history that does not yet hold them; `sessionKey` alone is optional, absent until a Prompt records a placement. Its presence locates state -and asserts neither native creation nor acceptance. Core takes both as +and asserts neither native creation nor acceptance. The Agent package takes both as detached, immutable snapshots when the request opens and delivers them only through this setup; they are not request members, Session properties or Context state, and possessing them authorizes no provider work. The structural adapter @@ -739,7 +740,7 @@ issuance. Middleware may transfer that whole route but cannot read, edit, copy or reattach its configuration. The owner and configuration operation are reachable through no Context, module registry, public Agent operation, middleware-readable member, return value or Session property. Another loaded -provider copy composes through the coordinator it received; another loaded Core +provider copy composes through the coordinator it received; another loaded Agent copy cannot manufacture a request or use this owner admits. A provider partition is one complete, independently owned agent-provider state — @@ -902,7 +903,7 @@ execution. Stop is scope cancellation rather than a fourth member. A held prompt can carry a host-supplied ordered list of PNG images. The ACPX provider sends them as image content blocks with the prompt text. The backend's -advertised image capability determines whether that turn can start. Core +advertised image capability determines whether that turn can start. The Agent package journals the text, and the caller supplies any durable references to the images. `prompt` returns source and runs none of it. A host that means to run what came @@ -910,7 +911,7 @@ back decides that itself and asks here, because a generated root is evaluated by the execution whose captured package documentation and canonical protected dispatch it reads — and that execution is this conversation's. Evaluating sends no provider prompt and changes no configuration. The element obtains the actual -method on its own execution's handle through a Core-private readiness bridge +method on its own execution's handle through an Agent-private readiness bridge before the conversation is announced ready, so a handle that reports itself open is open for all three things it offers; the bridge carries that bound operation and nothing behind it, and `AgentConversationHost` stays an ordinary @@ -960,11 +961,11 @@ configuration record, prompt record or root terminal follows from the refusal. Ordinary Session and Prompt elements keep composing through `Agent` exactly as before. -Core keeps what it already owned. The one-use request is opened and closed by +The Agent package keeps what it already owned. The one-use request is opened and closed by the conversation, the configuration requirement travels inside its issuance, and the conversation retains private evidence of the exact `Session` settling that request produced: a provider that answers with a session it never settled, -or with another after settling, is refused before Core asks for a prompt +or with another after settling, is refused before the conversation asks for a prompt stream. That check is not the configuration check — `activate()` still happens inside the provider before any native effect — and neither is evidence of native identity, which only a turn's own canonical record establishes. @@ -1032,8 +1033,8 @@ never rewritten. The record is configuration, not identity: an absent Prompt outcome is never permission to replace it, and the native identity remains the canonical assertion a turn records. -**Where its provider state is.** Each turn's setup carries two snapshots Core -takes from the history when that turn opens its request (§The provider-factory +**Where its provider state is.** Each turn's setup carries two snapshots the +Agent package takes from the history when that turn opens its request (§The provider-factory seam): the native conversation the history's Prompt records assert, and the initial record's provider and command with the latest nonempty `sessionKey` a Prompt record names — a failed turn's placement included, since the provider @@ -1159,7 +1160,7 @@ back. ### Saved Prompt failure details A failed owning stream release is terminal before ordinary failure -serialization and publication. Core preserves initiating work and teardown +serialization and publication. The Agent package preserves initiating work and teardown failures separately and activates the existing live publication failure path without a recoverable failed-turn record. Authored Catch therefore starts neither replacement work nor an unentered finalizer after failed release. @@ -1188,7 +1189,7 @@ message-only upstream failure remains undiagnosed. Diagnostics establish neither backend acceptance nor a successful retry and never enter the agent's reply text. -Core selects these optional facts before constructing the saved failure. With +The Agent package selects these optional facts before constructing the saved failure. With secret detection enabled, it screens each optional textual field in its retained JSON representation, omits offending fields, then screens the complete selected diagnostic. Unsafe secondary text does not discard a safe protocol @@ -1343,7 +1344,7 @@ canonical Prompt authors, may be observed but is retained nowhere and lends its usage to no neighbouring Prompt. Native-launch materialization keeps its own `MaterializationUsage` on its own record. -Core selects the retained value under the producing execution's protection +The Agent package selects the retained value under the producing execution's protection before the record is serialized. Each optional string — identities, build versions and digests, model names, currency — is withheld on its own when it fails the secret scanner or matches a protected input, which a scanner opt-out @@ -1358,7 +1359,7 @@ reaching a provider, refreshing a measurement or recording more spend. #### How a provider reports it -The coordinator Core delivers to an installed provider carries one optional +The coordinator the Agent package delivers to an installed provider carries one optional member: ```ts @@ -1368,7 +1369,7 @@ promptUsage?(): Operation; A provider calls it once when its stream is actually subscribed, before any native work, and keeps the receiver for that turn. The receiver belongs to that -one subscription: Core opens it when the subscription starts, keeps it open +one subscription: the Agent package opens it when the subscription starts, keeps it open through the subscription's joined teardown and seals it afterwards, so a retained receiver records nothing later and two subscriptions of one cold stream never share one. A canonical turn whose stream was subscribed more than once @@ -1378,7 +1379,7 @@ outcome. An absent member, an undefined receiver and a report that never came all leave usage unknown and refuse nothing. The same delivered coordinator carries an optional `promptUsage()` receiver, the one -route by which a provider's turn readings reach the Prompt that consumed them. Core +route by which a provider's turn readings reach the Prompt that consumed them. The Agent package creates one usage destination per actual stream subscription inside the audited stream that already carries the permission ledger, opens it before the provider's own subscription and seals it after that subscription's teardown joins; the canonical @@ -1792,7 +1793,7 @@ ends the whole authorship execution, so a turn that streamed text and then failed presents nothing. Those refusals are installed on a scope holding the document execution and -nothing else, so what the ceiling covers is what it says it covers. It cannot tell the host's own acts from the document's on its own: a call carries no mark saying who made it, and a provider's work happens inside the execution that reached it — core constructs a root provider from within the document — so a refusal over that scope covers both parties. Two things the command +nothing else, so what the ceiling covers is what it says it covers. It cannot tell the host's own acts from the document's on its own: a call carries no mark saying who made it, and a provider's work happens inside the execution that reached it — the Agent package constructs a root provider from within the document — so a refusal over that scope covers both parties. Two things the command does are the host's, and both run a command: installing this build's adapter, and opening the review form in a browser. The command therefore takes its own scope before it installs the ceiling and states those two acts as its own; they diff --git a/specs/executable-mdx-spec.md b/specs/executable-mdx-spec.md index 1eb1c3679..d4697b5df 100644 --- a/specs/executable-mdx-spec.md +++ b/specs/executable-mdx-spec.md @@ -2968,20 +2968,26 @@ renders each selected component's symbol metadata followed by the long-form documentation its owning package ships, once each, **in symbol order** whatever order they were asked for in. `as` captures the same text in either form. -Documentation joins to metadata by component name **and owning package**. Only a -registration and a protected component come from a package; a repository file, a +Documentation joins to metadata by component name **and registered origin**: +the documentation a boundary contributes names the origin its registrations +declare, and only those components receive it. Only a registration and a +protected component carry a registered origin; a repository file, a bundled blob and declared Markdown are this run's, so a repository `Elicit.md` receives none of the built-in `Elicit`'s prose. **A first-party package documents every component it supplies.** The index is -built from one `components.md` per registration boundary — core's own, its Agent -registrations, the CLI, testing, web and the repository-composition set — each +built from one `components.md` per registration boundary — core's own, the +Agent package's, the CLI, testing, web and the repository-composition set — each contributed by that boundary's own bootstrap from the same declarations it registers, so a component added to a package demands documentation without -anyone maintaining a second list. What `xmd syntax NAME` and a document's own +anyone maintaining a second list. The Agent package's components keep the +origin `@executablemd/core` they registered under before they moved out of +Core, because canonical resolution and retained journals identify a component +by that origin; its `components.md` contributes under the same origin, and the +index merges it with Core's own. What `xmd syntax NAME` and a document's own `` each read is the one snapshot canonical execution captured at collection, which is what makes them one index rather than two. A boundary that supplies a component with no section refuses the whole index — as does an unknown heading, a duplicate, and a -component documented twice for one package. A partially documented first-party +component documented twice for one origin. A partially documented first-party package is not a valid build: a reader cannot tell an undocumented component from one that has nothing to say, and the product's own reference would be silently incomplete. diff --git a/specs/native-agent-session-launch-spec.md b/specs/native-agent-session-launch-spec.md index ca0c5dfea..a5ae3149a 100644 --- a/specs/native-agent-session-launch-spec.md +++ b/specs/native-agent-session-launch-spec.md @@ -154,12 +154,13 @@ is discarded. Identity is object identity: a rebuilt look-alike, a superseded parent, a foreign request, or a second delegation of the same leaf describes the same ask and authorizes none of it. -The right to run and retain a phase never travels on that chain. Core delivers -one `AgentLaunchCoordinator` directly to the provider factory it installs, as an -argument the factory closes over — there is no context holding one, no request +The right to run and retain a phase never travels on that chain. The Agent package +delivers one `AgentLaunchCoordinator` directly to the provider factory it +installs, as an argument the factory closes over — there is no context holding one, no request member carrying one, and no reader for one. The coordinator validates the routed request and the provider's installation generation, runs each absent phase once, -cross-checks the returned record against the request, retains it before the next +cross-checks the returned record against the request, retains it under the +component invocation identity Core issued the launching element before the next live effect, and derives the result. A provider supplies the work; it never supplies the verdict. @@ -191,7 +192,7 @@ launch defines no default of its own. ## Prepared session request -Core hands the provider a normalized request containing: +The Agent package hands the provider a normalized request containing: ```text agent @@ -267,7 +268,7 @@ configured refuses before the provider prepares anything. The configured use remains valid only while the provider-installation owner that issued it is live. The launch provider reads it through the coordinator delivered directly to that installation; a same-named Context, sibling run, -retained post-teardown value or another loaded Core copy cannot supply that +retained post-teardown value or another loaded Agent copy cannot supply that owner. Provider teardown invalidates lookup before a later launch can prepare anything. Finishing a session setup and its registration state do not participate in launch admission: `AgentLaunchRequest` remains the launch's one-use identity. @@ -1102,11 +1103,11 @@ an **empty** `nativeSessionId`, the executable binding, and the exact materialization plan this launch owes. A preparation is not a report of the conversation's name. -Core retains `prepared` *before* the turn starts. It then executes the turn and +The coordinator retains `prepared` *before* the turn starts. It then executes the turn and retains it as a separate durable `agent_prompt` — an ordinary prompt record, because that is what it is, and the sending is what must never be re-run. Only the backend's explicit acceptance of that turn promotes the provider record and -asserts the native identity. Core then retains `materialized`, and only after +asserts the native identity. The coordinator then retains `materialized`, and only after that detaches ACP ownership and launches the native UI. An **already-established** provider-returned session takes none of that path. @@ -1176,9 +1177,10 @@ instruction-file path, argv, environment, raw host message, credential or provider-private state. The provider does not write these records and cannot reach the thing that does. -It offers each phase as live work to the coordinator core delivered it; the -coordinator runs a phase only when the journal has none, retains what comes back -before the next live effect, and cross-checks the preparation against the exact +It offers each phase as live work to the coordinator the Agent package +delivered it; the coordinator runs a phase only when the journal has none, +retains what comes back under the launching element's Core-issued invocation +identity before the next live effect, and cross-checks the preparation against the exact request that was routed — instructions and digest, agent, requested session, cwd, the V1 empty additional-directory list, and permission mode. A record that changed what was asked would make the journal describe a launch nobody @@ -1512,7 +1514,7 @@ degrading: before any materialization turn, detach record or native process, and the successful preparation retains one canonical `configuration`. A launch that could not apply them refuses with `configuration-refused` and retains no - configuration. Core issued the frozen session use that carried both the exact + configuration. The Agent package issued the frozen session use that carried both the exact provider Session that finished its setup and these settings; the provider retains no desired-settings association, and a rebuilt use authorizes nothing. Middleware may route another whole Session, and the preparation describes only the final diff --git a/specs/release-process-spec.md b/specs/release-process-spec.md index d3ff532ab..c7a6f6c73 100644 --- a/specs/release-process-spec.md +++ b/specs/release-process-spec.md @@ -152,6 +152,12 @@ The bump touches nothing else. package, ordered with `needs:` so dependencies publish before dependents (leaves run in parallel), plus one `jsr` job for the whole workspace. + `@executablemd/agent` publishes after `core`, `durable-streams` and + `runtime`, which it depends on, and before `acp`, `workflow`, `test-agent` + and `cli`, which declare it. Those edges come from the manifests like every + other, so a package that starts importing Agent gains its edge at the next + regeneration. + That ordering is a publication guarantee, not a build one. Each job builds its own closure from the tag's checkout, so no job waits for another's artifact to reach npm. What the edges still buy is that a failed upstream publish @@ -686,7 +692,10 @@ The checks that hold this together, each proving a different build: - `scripts/tests/cli-npm-bin.test.ts` builds the real package, asserts every emitted `esm/src/documents/` asset is byte-identical to the source, checks that the emitted core and runtime manifests publish `./api` and that the - module behind it was emitted, runs the built bin with a `--plugin` an operator + module behind it was emitted, checks that the emitted core manifest declares + no Agent dependency while a Node consumer outside the checkout imports + `@executablemd/agent/api` and `@executablemd/agent/host` by package name and + receives the source entrypoints' exports, runs the built bin with a `--plugin` an operator would write, and then asks the built bin — from a directory that is not the package — which Plan `` Component source it would let a document write. The answer carries the origin and the SHA-256 of those bytes, so a build that shipped different ones, or none, @@ -740,6 +749,10 @@ maintained: - `PACKAGED_DOCUMENTATION` — each package's `components.md`, named individually because the directories they sit in are package source, and embedding those whole would carry the TypeScript into the binary a second time. + The Agent components' file is `packages/agent/src/components.md`. It moved + with them out of `packages/core/src/agent/`, and its prose still documents + the `@executablemd/core` origin they register under. `scripts/build-npm.ts` + copies the same `src/components.md` into the Agent npm package. `compileArguments()` builds the complete argv from them and refuses an unknown `--target` before anything is spawned. `scripts/compile.ts` is the command a