@yugoo-design/dsh-design-studio-dsh 0.1.2 → 0.2.0

package/lib/authoring-agent-Ci08ifdJ.js

@@ -0,0 +1,634 @@
+import { isAbsolute } from "node:path";
+import assert from "node:assert/strict";
+import { randomUUID } from "node:crypto";
+import { foldConsumedWork } from "@deepseek-ai/dsh-agent";
+import { SessionId } from "@deepseek-ai/dsh-session";
+import { createUserMessage } from "@deepseek-ai/dsh-llm";
+import { appendDelegatedPolicyOverrides, applyChildComposition, captureDelegatedPolicyOverrides, resolveChildAgentOptions, resolveChildDepth } from "@deepseek-ai/dsh-subagent";
+import { defineTool } from "@deepseek-ai/dsh-tools";
+import { open } from "node:fs/promises";
+import { PANEL_COMPONENT_CATALOG, queryPanelAuthoringReference } from "@yugoo-design/dsh-design-core/dsl";
+//#region src/authoring-material.ts
+/** Package-owned creator methods; model arguments select map keys, never files. */
+const MAX_MATERIAL_BYTES = 16777216;
+const MAX_RESOURCE_BYTES = 2097152;
+const MAX_TOTAL_BYTES = 4194304;
+const PAGE_BYTES = 16384;
+const record = (value) => !!value && typeof value === "object" && !Array.isArray(value);
+function textPage(bytes, offset = 0) {
+	if (!Number.isSafeInteger(offset) || typeof offset !== "number" || offset < 0 || offset > bytes.length || offset < bytes.length && (bytes[offset] & 192) === 128) throw new Error("Invalid authoring resource UTF-8 byte offset");
+	let end = Math.min(bytes.length, offset + PAGE_BYTES);
+	while (end < bytes.length && (bytes[end] & 192) === 128) end--;
+	return {
+		offset,
+		content: bytes.subarray(offset, end).toString("utf8"),
+		bytes: end - offset,
+		totalBytes: bytes.length,
+		...end < bytes.length ? { nextOffset: end } : {}
+	};
+}
+function createStudioAuthoringMaterialReader(value) {
+	if (!record(value) || value.schemaVersion !== 1 || !Array.isArray(value.skills) || !value.skills.length || !record(value.resources)) throw new Error("Packaged Studio authoring methods are unavailable");
+	const entries = Object.entries(value.resources);
+	if (!entries.length || entries.length > 128) throw new Error("Studio authoring material exceeds its resource budget");
+	const resources = /* @__PURE__ */ new Map();
+	let total = 0;
+	for (const [path, entry] of entries) {
+		if (!path || path.length > 1024 || path.startsWith("/") || path.includes("\\") || path.split("/").some((part) => !part || part === "." || part === "..") || !record(entry) || typeof entry.content !== "string") throw new Error("Invalid packaged Studio authoring resource");
+		const bytes = Buffer.from(entry.content, "utf8");
+		if (bytes.length !== entry.bytes || bytes.length > MAX_RESOURCE_BYTES || (total += bytes.length) > MAX_TOTAL_BYTES) throw new Error("Studio authoring material exceeds its text budget");
+		resources.set(path, bytes);
+	}
+	if (!resources.has("index.md") || value.skills.some((skill) => !record(skill) || typeof skill.name !== "string" || typeof skill.description !== "string" || typeof skill.method !== "string" || !resources.has(skill.method))) throw new Error("Packaged Studio authoring method index is incomplete");
+	const skills = value.skills.map((skill) => ({
+		name: skill.name,
+		description: skill.description,
+		method: skill.method
+	}));
+	return (input = {}) => {
+		if (!record(input) || Reflect.ownKeys(input).some((key) => key !== "resource" && key !== "offset")) throw new Error("Authoring methods accept only an indexed resource and byte offset");
+		const resource = input.resource === void 0 ? "index.md" : input.resource, offset = input.offset === void 0 ? 0 : input.offset;
+		if (typeof resource !== "string" || !resources.has(resource)) throw new Error("Unknown indexed Studio authoring resource");
+		return {
+			resource,
+			...textPage(resources.get(resource), offset),
+			...resource === "index.md" ? { skills: structuredClone(skills) } : {}
+		};
+	};
+}
+let packaged;
+async function readPackageJson(path, maxBytes) {
+	const handle = await open(new URL("../lib/authoring/" + path, import.meta.url), "r");
+	try {
+		const bytes = Buffer.alloc(maxBytes + 1);
+		let size = 0;
+		while (size < bytes.length) {
+			const result = await handle.read(bytes, size, bytes.length - size, size);
+			if (!result.bytesRead) break;
+			size += result.bytesRead;
+		}
+		if (size > maxBytes) throw new Error("Packaged Studio authoring material exceeds its budget");
+		return JSON.parse(bytes.subarray(0, size).toString("utf8"));
+	} finally {
+		await handle.close();
+	}
+}
+async function readStudioAuthoringMaterial(input = {}) {
+	packaged ??= readPackageJson("studio-creators/material.json", MAX_MATERIAL_BYTES).then(createStudioAuthoringMaterialReader);
+	return (await packaged)(input);
+}
+let panelMaterial;
+/** Same Core query and build-generated source references as the Companion tool. */
+async function readStudioPanelComponents(input = {}) {
+	if (!record(input) || Reflect.ownKeys(input).some((key) => ![
+		"name",
+		"reference",
+		"type",
+		"offset"
+	].includes(String(key)))) throw new Error("Invalid component reference request");
+	const { name, reference, type, offset } = input;
+	if (name !== void 0 && (typeof name !== "string" || !name || name.length > 128 || !Object.hasOwn(PANEL_COMPONENT_CATALOG, name))) throw new Error("Unknown panel component; read components:{} for the installed vocabulary");
+	if (reference !== void 0 || type !== void 0) {
+		if (typeof name !== "string" || ![
+			"contract",
+			"docs",
+			"examples"
+		].includes(reference) || type !== void 0 && (reference !== "contract" || typeof type !== "string" || !type || type.length > 256)) throw new Error("Component references require an exact name and contract/docs/examples; type is valid only for contract");
+		panelMaterial ??= readPackageJson("panel-components.json", 6e6);
+		const result = queryPanelAuthoringReference(await panelMaterial, name, reference, type);
+		const bytes = Buffer.from(JSON.stringify(result), "utf8");
+		if (bytes.length > 262144) throw new Error("Component authoring response exceeds its 256 KiB budget; follow an exact contract type");
+		return bytes.length > PAGE_BYTES || offset !== void 0 ? {
+			component: name,
+			reference,
+			format: "json",
+			...textPage(bytes, offset)
+		} : result;
+	}
+	if (offset !== void 0) throw new Error("Component offsets require an exact reference");
+	return {
+		components: Object.entries(PANEL_COMPONENT_CATALOG).filter(([kind]) => name === void 0 || kind === name).map(([kind, entry]) => ({
+			name: kind,
+			...entry,
+			generated: "autoOrder" in entry && entry.autoOrder !== void 0
+		})),
+		contract: "Runtime vocabulary and composition guidance only; not a complete parameter schema or standard A2UI specification."
+	};
+}
+const STUDIO_AUTHORING_METHOD_GUIDANCE = "Before proposing Kit/Bundle source changes, read the packaged creator method index and the applicable complete methods and linked resources. Follow every nextOffset until each required resource is complete; index summaries do not replace methods. Read the exact working copy and its own method/output contract too. Preserve its existing catalog identity, runtime name and version in their respective source files; display titles do not rename those identities. For Panel changes, read authoring:{resource:\"source/docs/dsl-spec.md\"} for the complete manifest, including required root fields; a component contract describes only part of that manifest. Discover components:{} and read the selected exact component with components:{name,reference:\"contract\"}, then its docs/examples and referenced type declarations before choosing parameters. Large component references return JSON text pages: keep the same selectors and follow nextOffset with components.offset until complete. Follow the returned selectors for allowed values instead of guessing from component names. When repairing diagnostics, retain already-correct changes and replace only the diagnosed assumptions. If a method or component contract is unavailable, report the gap instead of inventing it.";
+//#endregion
+//#region src/authoring-agent.ts
+/** Restricted native Studio authoring; candidate preparation never saves content. */
+const MAX_EVENTS = 8192;
+const PREPARE_REPLACEMENT_GUIDANCE = "Each prepare starts from the bound saved revision and replaces the entire previous unsaved proposal; calls do not accumulate. When correcting diagnostics, resend the full set of all still-intended unsaved file replacements, including unchanged files from the previous proposal.";
+const clone = (value) => structuredClone(value);
+const encode = (value) => JSON.stringify(value);
+function snapshotScope(value) {
+	const scope = clone(value);
+	assert.ok(typeof scope.id === "string" && scope.id.length > 0);
+	assert.ok(Number.isSafeInteger(scope.expectedRevision) && scope.expectedRevision >= 0);
+	assert.ok(Array.isArray(scope.allowedPaths) && scope.allowedPaths.length > 0 && scope.allowedPaths.every((path) => typeof path === "string" && path.length > 0));
+	Object.freeze(scope.allowedPaths);
+	if (scope.bundle) Object.freeze(scope.bundle);
+	return Object.freeze(scope);
+}
+function messageBinding(message) {
+	if (message.source.kind !== "yugoo-design") return;
+	return message.source.studioAuthoring;
+}
+/** Inbox state is needed to distinguish unrun cancellation from an empty turn. */
+function account(events, reference) {
+	const queues = /* @__PURE__ */ new Map(), owned = events.filter((event) => event.seq > reference.afterSeq);
+	let turn = null, consumedTurn = null, dropped = false, bound = false;
+	for (const event of events) {
+		if (event.type === "turn/start" && event.seq > reference.afterSeq) turn = event.data.turn;
+		if (event.type === "agent/inbox/spliced") {
+			const data = event.data, queue = queues.get(data.target) ?? [];
+			const removed = queue.splice(data.start, data.removedCount ?? 0, ...data.inserted);
+			queues.set(data.target, queue);
+			for (const message of data.inserted) if (message.id === reference.messageId) {
+				const { messageId: _id, ...expected } = reference;
+				assert.deepEqual(messageBinding(message), expected, "Native Studio binding differs from the retained reference");
+				bound = true;
+			}
+			if (removed.some((message) => message.id === reference.messageId)) {
+				if (data.outcome === "canceled") dropped = true;
+				else if (turn !== null) consumedTurn = turn;
+			}
+		}
+		if (event.type === "user/message" && event.data.id === reference.messageId) {
+			const { messageId: _id, ...expected } = reference;
+			assert.deepEqual(messageBinding(event.data), expected, "Native Studio message binding mismatch");
+			bound = true;
+			consumedTurn = turn;
+		}
+	}
+	const pendingInput = [...queues.values()].some((queue) => queue.length > 0);
+	const consumed = consumedTurn !== null;
+	const startIndex = owned.findIndex((event) => event.type === "turn/start" && event.data.turn === consumedTurn);
+	const endIndex = owned.findIndex((event) => event.type === "turn/end" && event.data.turn === consumedTurn);
+	const end = startIndex >= 0 && endIndex >= startIndex ? foldConsumedWork(owned.slice(startIndex, endIndex + 1)).end : void 0;
+	const matchingEnd = end && consumed && end.data.turn === consumedTurn ? end : void 0;
+	const reason = matchingEnd?.data.reason.kind;
+	const interrupted = reason === "interrupted" || reason === "forked";
+	return {
+		bound,
+		status: interrupted ? "unknown" : dropped || reason === "aborted" ? "cancelled" : reason === "completed" ? "completed" : matchingEnd ? "failed" : consumed ? "running" : bound ? "queued" : "unknown",
+		consumed,
+		turn: consumedTurn ?? turn,
+		terminal: !interrupted && (dropped || !!matchingEnd),
+		reason,
+		pendingInput,
+		throughSeq: events.at(-1)?.seq ?? -1
+	};
+}
+/** Public Host records for this exact request; execution remains native. */
+function conversation(events, ref, state) {
+	const rows = [];
+	const calls = /* @__PURE__ */ new Map();
+	for (const event of events) {
+		if (event.seq <= ref.afterSeq) continue;
+		if (event.type === "assistant/message" && event.surfaceOp === "append") {
+			const text = event.data.message.content.flatMap((block) => block.type === "text" ? [block.text] : []).join("\n").slice(0, 16384);
+			if (text) rows.push({
+				id: String(event.data.message.id),
+				role: "assistant",
+				label: "Agent",
+				text,
+				status: "completed"
+			});
+		} else if (event.type === "tool/call") {
+			const row = {
+				id: String(event.data.callId),
+				role: "tool",
+				label: event.data.name,
+				text: "",
+				status: "running"
+			};
+			rows.push(row);
+			calls.set(row.id, row);
+		} else if (event.type === "tool/result" && event.surfaceOp === "append") {
+			const row = calls.get(String(event.data.message.toolCallId));
+			if (row) {
+				row.status = event.data.message.isError ? "failed" : "completed";
+				row.text = event.data.error?.reason?.slice(0, 16384) ?? "";
+			}
+		}
+	}
+	if (state.terminal) {
+		for (const row of calls.values()) if (row.status === "running") row.status = state.status === "cancelled" ? "cancelled" : "unknown";
+	}
+	return {
+		rows: rows.slice(-200),
+		omitted: Math.max(0, rows.length - 200)
+	};
+}
+/** Host-owned adapter. No filesystem store, provider client, or native profile is created. */
+function createStudioAuthoringAgent(ctx) {
+	const live = /* @__PURE__ */ new Map();
+	const starting = /* @__PURE__ */ new Set();
+	const cleanupFailures = /* @__PURE__ */ new Set();
+	const lifetime = new AbortController();
+	let disposing;
+	const durable = /* @__PURE__ */ new Set();
+	const key = (ref) => `${ref.sessionId}:${ref.epoch}`;
+	async function observe(reference) {
+		const ref = clone(reference), lease = await ctx.sessionQuery.observeSession(SessionId(ref.sessionId), { projectionMode: "none" });
+		try {
+			assert.equal(String(lease.header.id), ref.sessionId);
+			assert.equal(String(lease.header.parentSession), ref.parentSessionId, "Native Studio parent changed");
+			assert.ok(lease.events.length <= MAX_EVENTS, "Studio native evidence exceeds the bounded observation limit");
+			const next = lease.events.find((event) => event.seq > ref.afterSeq && event.type === "agent/inbox/spliced" && event.data.inserted.some((message) => messageBinding(message)?.epoch !== void 0 && messageBinding(message)?.epoch !== ref.epoch));
+			const events = next ? lease.events.filter((event) => event.seq < next.seq) : lease.events;
+			const { bound, ...state } = account(events, ref);
+			return {
+				reference: ref,
+				...state,
+				source: lease.source,
+				durable: durable.has(key(ref)),
+				conversation: bound ? conversation(events, ref, state) : {
+					rows: [],
+					omitted: 0
+				}
+			};
+		} finally {
+			lease[Symbol.dispose]();
+		}
+	}
+	async function start(request, previous) {
+		const { invocationId, workspaceRoot, prompt, signal: callerSignal, onReference, onPrepared } = request;
+		const signal = callerSignal ? AbortSignal.any([callerSignal, lifetime.signal]) : lifetime.signal;
+		const waitFor = (operation) => new Promise((resolve, reject) => {
+			signal.throwIfAborted();
+			const onAbort = () => reject(signal.reason);
+			signal.addEventListener("abort", onAbort, { once: true });
+			Promise.resolve().then(() => {
+				signal.throwIfAborted();
+				return operation();
+			}).then((value) => {
+				signal.removeEventListener("abort", onAbort);
+				resolve(value);
+			}, (error) => {
+				signal.removeEventListener("abort", onAbort);
+				reject(error);
+			});
+		});
+		previous = previous === void 0 ? void 0 : clone(previous);
+		signal?.throwIfAborted();
+		const scope = snapshotScope(request.scope), parent = request.parent;
+		assert.equal(ctx.agents.get(parent.id), parent, "Studio requires the exact live native parent");
+		assert.ok(isAbsolute(workspaceRoot), "Studio requires an explicit isolated native workspace");
+		assert.ok(typeof invocationId === "string" && invocationId.length > 0);
+		assert.ok(typeof prompt === "string" && prompt.trim() && Buffer.byteLength(prompt) <= 131072);
+		const read = request.ports.read.bind(request.ports), prepare = request.ports.prepare.bind(request.ports);
+		const checked = await waitFor(() => read({ paths: [scope.allowedPaths[0]] }));
+		assert.deepEqual(checked.scope, scope, "S3 authoring scope differs from the native binding");
+		signal?.throwIfAborted();
+		assert.equal(ctx.agents.get(parent.id), parent, "Studio caller closed during source preflight");
+		if (previous) {
+			assert.equal(previous.parentSessionId, String(parent.id), "Studio resume parent changed");
+			assert.equal(previous.scope.id, scope.id, "Studio resume cannot select another instance");
+			assert.ok(scope.expectedRevision >= previous.scope.expectedRevision, "Studio resume cannot restore an older source revision");
+			const prior = await waitFor(() => observe(previous));
+			assert.ok(!prior.pendingInput && prior.consumed, "Native delivery is unconsumed or unknown; do not redispatch it");
+			assert.equal(ctx.agents.get(SessionId(previous.sessionId)), void 0, "Native Studio session is already live");
+		}
+		const sessionId = previous?.sessionId ?? randomUUID(), epoch = randomUUID();
+		const events = [], staged = /* @__PURE__ */ new Map();
+		let child, handle, ref;
+		let currentTurn = null, finished = false, prepared, diagnostic;
+		let overflow = false, disposed;
+		const policy = captureDelegatedPolicyOverrides(parent), depth = resolveChildDepth(parent, void 0);
+		const disposeOwned = () => disposed ??= (async () => {
+			try {
+				await handle?.dispose();
+			} catch (error) {
+				cleanupFailures.add(error);
+				throw error;
+			}
+		})();
+		const onAbort = () => queueMicrotask(() => {
+			if (!finished && child && ctx.agents.get(child.id) === child) child.cancel({ kind: "parent" });
+		});
+		const setup = (childCtx, agent) => {
+			signal.throwIfAborted();
+			assert.equal(agent.session.header.cwd, workspaceRoot, "Native Studio workspace changed; explicit migration is required");
+			child = agent;
+			appendDelegatedPolicyOverrides(agent.session, policy);
+			appendDelegatedPolicyOverrides(agent.session, {
+				sandboxMode: "read-only",
+				approvalPolicy: "never",
+				permissionPreset: void 0
+			});
+			applyChildComposition(childCtx, parent, { toolFilter: { allow: [] } });
+			childCtx.tools.presentAs("native");
+			childCtx.on("session/event", (session, event) => {
+				if (session !== agent.session) return;
+				if (event.type === "turn/start") currentTurn = event.data.turn;
+				if (events.length < MAX_EVENTS) events.push(event);
+				else overflow = true;
+			});
+			const definitions = /* @__PURE__ */ new Map();
+			const register = (definition) => {
+				Object.freeze(definition);
+				definitions.set(definition.name, definition);
+				childCtx.tools.register(definition);
+			};
+			const output = {
+				schema: {
+					type: "object",
+					properties: { content: {
+						type: "string",
+						required: true
+					} },
+					additionalProperties: false
+				},
+				render: (_args, value) => [{
+					type: "text",
+					text: value.content
+				}]
+			};
+			const returned = (value) => {
+				const content = encode(value);
+				assert.ok(content !== void 0 && Buffer.byteLength(content) <= 5242880, "Studio tool receipt exceeds its bounded budget");
+				return { content };
+			};
+			register(defineTool({
+				name: "studio_authoring_read",
+				description: "Read the exact bound Studio source, packaged creator methods with authoring:{resource?,offset?}, or actual component references with components:{name?,reference?,type?,offset?}. Read authoring:{} for the index first and follow nextOffset. Discover components:{}, then read an exact name with reference contract/docs/examples; type selects a referenced contract declaration only. Large references are JSON text pages; follow nextOffset with the same selectors and components.offset. These are read-only guidance, not editable source. Scope is fixed by the Host; no project or arbitrary filesystem access.",
+				parameters: {
+					paths: {
+						type: "array",
+						items: { type: "string" }
+					},
+					authoring: {
+						type: "object",
+						properties: {
+							resource: { type: "string" },
+							offset: { type: "integer" }
+						},
+						additionalProperties: false
+					},
+					components: {
+						type: "object",
+						properties: {
+							name: { type: "string" },
+							reference: {
+								type: "string",
+								enum: [
+									"contract",
+									"docs",
+									"examples"
+								]
+							},
+							type: { type: "string" },
+							offset: { type: "integer" }
+						},
+						additionalProperties: false
+					}
+				},
+				output,
+				async execute(args, exec) {
+					exec.signal.throwIfAborted();
+					if (args.authoring !== void 0 && Object.keys(args).some((key) => key !== "authoring")) throw new Error("Read authoring methods separately from bound source paths");
+					if (args.components !== void 0 && Object.keys(args).some((key) => key !== "components")) throw new Error("Read component references separately from bound source paths");
+					const value = args.authoring !== void 0 ? await readStudioAuthoringMaterial(args.authoring) : args.components !== void 0 ? await readStudioPanelComponents(args.components) : await read(args);
+					exec.signal.throwIfAborted();
+					return returned(value);
+				}
+			}));
+			register(defineTool({
+				name: "studio_authoring_prepare",
+				description: `Prepare full-file additions and replacements through S1 for human diff/real-preview review. Read, replace or add source files within this working copy. The initial allowedPaths list is a reading focus, not a file-edit restriction. ${PREPARE_REPLACEMENT_GUIDANCE} Never saves or publishes. Finish after a valid candidate.`,
+				parameters: { changes: {
+					type: "array",
+					required: true,
+					items: {
+						type: "object",
+						properties: {
+							path: {
+								type: "string",
+								required: true
+							},
+							content: {
+								type: "string",
+								required: true
+							}
+						},
+						additionalProperties: false
+					}
+				} },
+				output,
+				async execute(args, exec) {
+					exec.signal.throwIfAborted();
+					const changes = args.changes.map((change) => {
+						assert.ok(typeof change.path === "string" && typeof change.content === "string", "Complete Studio replacement required");
+						return {
+							path: change.path,
+							content: change.content
+						};
+					});
+					const value = await prepare({ changes });
+					exec.signal.throwIfAborted();
+					const response = returned(value);
+					staged.set(exec.token, clone(value));
+					return response;
+				}
+			}));
+			childCtx.tools.guard((exec) => signal.aborted || exec.agent !== agent || exec.parent !== void 0 || finished || ctx.agents.get(parent.id) !== parent || !definitions.has(exec.name) || childCtx.tools.get(exec.name, agent) !== definitions.get(exec.name) ? "Operation is outside the exact Studio read/prepare capability" : void 0);
+			childCtx.on("tools/result", (exec, result) => {
+				if (exec.agent !== agent || !staged.has(exec.token)) return;
+				const value = staged.get(exec.token);
+				staged.delete(exec.token);
+				if (result.isError || exec.signal.aborted || signal?.aborted || ctx.agents.get(parent.id) !== parent) return;
+				prepared = value;
+				const projectionFailed = () => {
+					diagnostic = "Candidate projection failed; the same S3 receipt remains available through readPrepared.";
+				};
+				try {
+					Promise.resolve(onPrepared?.(clone(value))).catch(projectionFailed);
+				} catch {
+					projectionFailed();
+				}
+			});
+			const manifestIdentity = scope.bundle ? `For the selected Bundle manifest: Set skill.yaml identity to ${encode(scope.bundle.name)} and version to ${encode(scope.bundle.version)}. Keep skill.yaml name and SKILL.md frontmatter name as the runtime name read from SKILL.md; the catalog identity is separate and must not replace that runtime name.` : "";
+			childCtx.systemPrompt.section({
+				name: "studio:customization-methods",
+				order: 550,
+				text: `Work only on this Host-bound Studio source scope: ${encode(scope)}. ${manifestIdentity} ${STUDIO_AUTHORING_METHOD_GUIDANCE} Use studio_authoring_read with {authoring:{}} for the creator index, then {authoring:{resource,offset}} for its exact resources. Read bound source and the actual component catalog separately with {paths:[...]}. Use studio_authoring_prepare for full-file candidates, including new source files in this working copy; allowedPaths names the initial read only, and validation/preview diagnostics come from S1. ${PREPARE_REPLACEMENT_GUIDANCE} No filesystem, shell, project/GRA, save, publication, or delegation is granted. A prepared candidate is for human review, not saved content. Finish your native turn after preparing the requested candidate.`
+			});
+		};
+		try {
+			const common = {
+				parentAgent: parent,
+				agentOptions: resolveChildAgentOptions(parent, void 0, depth),
+				signal,
+				setup
+			};
+			handle = previous ? await parent.ctx.agents.resume({
+				...common,
+				resumeSessionId: SessionId(sessionId)
+			}) : await parent.ctx.agents.create({
+				...common,
+				sessionId: SessionId(sessionId),
+				meta: {
+					cwd: workspaceRoot,
+					parentSession: parent.session.id,
+					delegationDepth: depth,
+					isSeeded: false
+				}
+			});
+			signal.throwIfAborted();
+			assert.equal(String(handle.agent.id), sessionId);
+			const lease = await ctx.sessionQuery.observeSession(SessionId(sessionId), { projectionMode: "none" });
+			let afterSeq;
+			try {
+				signal.throwIfAborted();
+				afterSeq = lease.cursor;
+			} finally {
+				lease[Symbol.dispose]();
+			}
+			const binding = {
+				sessionId,
+				parentSessionId: String(parent.id),
+				invocationId,
+				epoch,
+				afterSeq,
+				scope
+			};
+			const message = createUserMessage({
+				source: {
+					kind: "yugoo-design",
+					studioAuthoring: binding
+				},
+				content: [{
+					type: "text",
+					text: prompt
+				}]
+			});
+			ref = Object.freeze({
+				...binding,
+				messageId: String(message.id)
+			});
+			await waitFor(() => onReference?.(clone(ref)));
+			signal?.throwIfAborted();
+			signal?.addEventListener("abort", onAbort, { once: true });
+			signal?.throwIfAborted();
+			try {
+				handle.agent.followup(message);
+			} catch {
+				diagnostic = "Native dispatch acknowledgement is unknown; do not redispatch this input.";
+			}
+		} catch (error) {
+			await disposeOwned();
+			throw error;
+		}
+		const reference = ref, owned = handle;
+		const result = (async () => {
+			try {
+				await owned.agent.whenIdle();
+				if (await ctx.sessions.flush(owned.agent.session) && ctx.get("sessionPersistence")) {
+					durable.add(key(reference));
+					if (durable.size > 256) durable.delete(durable.values().next().value);
+				}
+				const observation = await observe(reference);
+				if (overflow) return {
+					...observation,
+					status: "unknown",
+					terminal: false,
+					diagnostic: "Native evidence limit exceeded; retain and inspect the original session."
+				};
+				return diagnostic ? {
+					...observation,
+					diagnostic
+				} : observation;
+			} catch {
+				return {
+					reference,
+					status: "unknown",
+					consumed: false,
+					turn: currentTurn,
+					terminal: false,
+					throughSeq: events.at(-1)?.seq ?? reference.afterSeq,
+					source: "live",
+					durable: durable.has(key(reference)),
+					pendingInput: true,
+					diagnostic: "Native settlement or persistence could not be verified; retain this address and inspect without redispatch."
+				};
+			} finally {
+				finished = true;
+				signal?.removeEventListener("abort", onAbort);
+				await disposeOwned();
+				live.delete(key(reference));
+			}
+		})();
+		result.catch(() => {});
+		const run = {
+			reference,
+			result,
+			observe: () => observe(reference),
+			readPrepared: () => prepared === void 0 ? void 0 : clone(prepared),
+			cancel({ expectedTurn }) {
+				if (finished) return result;
+				assert.equal(ctx.agents.get(owned.agent.id), owned.agent, "Native Studio handle is no longer owned");
+				assert.equal(currentTurn, expectedTurn, "Native Studio turn changed; refresh before stopping");
+				owned.agent.cancel({ kind: "user" });
+				return result;
+			},
+			async dispose() {
+				if (!finished) owned.agent.cancel({ kind: "disposed" });
+				await result;
+				await disposeOwned();
+			}
+		};
+		live.set(key(reference), run);
+		return Object.freeze(run);
+	}
+	async function admit(request, previous) {
+		lifetime.signal.throwIfAborted();
+		let settled;
+		const pending = new Promise((resolve) => {
+			settled = resolve;
+		});
+		starting.add(pending);
+		try {
+			const run = await start(request, previous);
+			if (lifetime.signal.aborted) {
+				await run.dispose();
+				lifetime.signal.throwIfAborted();
+			}
+			return run;
+		} finally {
+			starting.delete(pending);
+			settled();
+		}
+	}
+	/** Permanently close admission, then drain both startup and owned native runs. */
+	const dispose = () => {
+		if (disposing) return disposing;
+		let resolve, reject;
+		disposing = new Promise((done, failed) => {
+			resolve = done;
+			reject = failed;
+		});
+		lifetime.abort(/* @__PURE__ */ new Error("Studio authoring adapter is disposed"));
+		Promise.allSettled([...starting, ...[...live.values()].map((run) => Promise.resolve().then(() => run.dispose()))]).then((settled) => {
+			const failures = /* @__PURE__ */ new Set([...cleanupFailures, ...settled.filter((value) => value.status === "rejected").map((value) => value.reason)]);
+			if (failures.size) reject(new AggregateError([...failures], "Owned Studio native cleanup failed"));
+			else resolve();
+		});
+		return disposing;
+	};
+	ctx.effect(() => dispose);
+	return Object.freeze({
+		start: (request) => admit(request),
+		observe,
+		dispose,
+		resume(request) {
+			assert.equal(request.explicit, true, "Native Studio continuation requires explicit authorization");
+			return admit(request, request.previous);
+		}
+	});
+}
+//#endregion
+export { readStudioPanelComponents as i, STUDIO_AUTHORING_METHOD_GUIDANCE as n, readStudioAuthoringMaterial as r, createStudioAuthoringAgent as t };

package/lib/authoring-agent.d.ts

@@ -0,0 +1,24 @@
+import { a as StudioAuthoringResumeRequest, i as StudioAuthoringRequest, n as StudioAuthoringPorts, o as StudioAuthoringRun, r as StudioAuthoringReference, s as StudioAuthoringScope, t as StudioAuthoringObservation } from "./authoring-agent.types-QLa61eE6.js";
+import { Context } from "@deepseek-ai/cordis";
+//#region src/authoring-agent.d.ts
+declare module '@deepseek-ai/dsh-llm' {
+  interface MessageSourceMap {
+    'yugoo-design': {
+      readonly kind: 'yugoo-design';
+    } & ({
+      readonly form?: never;
+    } | {
+      readonly form: 'notice';
+      readonly summary: string;
+    });
+  }
+}
+/** Host-owned adapter. No filesystem store, provider client, or native profile is created. */
+declare function createStudioAuthoringAgent(ctx: Context): Readonly<{
+  start: (request: StudioAuthoringRequest) => Promise<StudioAuthoringRun>;
+  observe: (reference: StudioAuthoringReference) => Promise<StudioAuthoringObservation>;
+  dispose: () => Promise<void>;
+  resume(request: StudioAuthoringResumeRequest): Promise<StudioAuthoringRun>;
+}>;
+//#endregion
+export { type StudioAuthoringObservation, type StudioAuthoringPorts, type StudioAuthoringReference, type StudioAuthoringRequest, type StudioAuthoringResumeRequest, type StudioAuthoringRun, type StudioAuthoringScope, createStudioAuthoringAgent };

package/lib/authoring-agent.js

@@ -0,0 +1,2 @@
+import { t as createStudioAuthoringAgent } from "./authoring-agent-Ci08ifdJ.js";
+export { createStudioAuthoringAgent };