@deepseek-ai/dsh-api-remotes 0.0.1-rc.1

package/lib/index.js

@@ -0,0 +1,142 @@
+import { TypeRTLookupFailure } from "@deepseek-ai/dsh-type-meta";
+//#region lib/types/agent-lookup.js
+/** Host BFF policy for resolving Remote Agent and Session identities. */
+/** Cold identity absent from the durable session store. */
+var ApiRemoteSessionNotFound = class extends Error {};
+/** Session identity whose lifecycle belongs to subagent routing. */
+var ApiRemoteSubagentSessionOwnership = class extends Error {
+	sessionId;
+	/**
+	* Construct the ownership fence.
+	* @param sessionId - identity reserved to subagent routing.
+	*/
+	constructor(sessionId) {
+		super(`session "${sessionId}" is a subagent session; use subagent delivery`);
+		this.sessionId = sessionId;
+	}
+};
+/**
+* Test whether generic Host routing must leave an identity to subagent routing.
+* @param ctx - Host Context carrying the live Agent registry.
+* @param session - attached or live Session metadata.
+* @param agent - live Agent when one is registered.
+* @returns whether generic Remote and legacy API calls must reject the identity.
+*/
+function hasApiRemoteSubagentOwner(ctx, session, agent) {
+	if (session.header.origin === "subagent") return true;
+	const parentId = session.header.parentSession;
+	if (parentId === void 0 || agent === void 0) return false;
+	const parent = ctx.agents.get(parentId);
+	return parent !== void 0 && ctx.agents.isOwnedBy(agent.id, parent);
+}
+/**
+* Build the stable caller-facing ownership rejection.
+* @param sessionId - identity reserved to subagent routing.
+* @returns the existing `agent-busy` RPC shape.
+*/
+function apiRemoteSubagentOwnershipError(sessionId) {
+	return {
+		code: "agent-busy",
+		message: `session "${sessionId}" is owned by subagent routing`,
+		details: { reason: "use subagent delivery for this child session" }
+	};
+}
+/**
+* Inspect one cold served session without repairing, resuming, or publishing it.
+* @param ctx - Host Context carrying the optional persistence provider.
+* @param sessionId - durable identity to inspect.
+* @returns detached metadata and events for a servable session.
+* @throws {@link ApiRemoteSessionNotFound} when the identity has no project-backed session.
+*/
+async function inspectApiRemoteSession(ctx, sessionId) {
+	const persistence = ctx.get("sessionPersistence");
+	if (persistence === void 0) throw new Error("session persistence is not configured (load a dsh-session-persistence backend)");
+	const meta = (await persistence.list()).find((candidate) => candidate.id === sessionId);
+	if (meta === void 0 || meta.cwd === void 0) throw new ApiRemoteSessionNotFound(`session "${sessionId}" not found`);
+	const inspected = await persistence.inspect(sessionId);
+	if (inspected.meta.cwd === void 0) throw new ApiRemoteSessionNotFound(`session "${sessionId}" not found`);
+	return {
+		meta: inspected.meta,
+		events: [...inspected.events]
+	};
+}
+/**
+* Create the Host's shared Agent resolver and configure Agent/Session TypeRT lookups.
+* Live Agents are reused, ordinary cold sessions resume once per identity, and
+* subagent-owned identities retain the legacy `agent-busy` fence.
+* @param ctx - owning Host Context.
+* @param options - defaults and Agent-scope setup used only for cold resume.
+* @returns resolver shared by legacy API Proxy methods and TypeRT lookups.
+*/
+function createApiRemoteAgentResolver(ctx, options) {
+	const resumes = /* @__PURE__ */ new Map();
+	const fencedLiveAgent = (sessionId) => {
+		const live = ctx.agents.get(sessionId);
+		if (live === void 0) return void 0;
+		if (hasApiRemoteSubagentOwner(ctx, live.session, live)) return { error: apiRemoteSubagentOwnershipError(sessionId) };
+		return { agent: live };
+	};
+	const agentFor = async (sessionId) => {
+		const fenced = fencedLiveAgent(sessionId);
+		if (fenced !== void 0) return fenced;
+		const attached = ctx.sessions.get(sessionId);
+		if (attached !== void 0 && hasApiRemoteSubagentOwner(ctx, attached, void 0)) return { error: apiRemoteSubagentOwnershipError(sessionId) };
+		let resume = resumes.get(sessionId);
+		if (resume === void 0) {
+			resume = (async () => {
+				try {
+					const inspected = await inspectApiRemoteSession(ctx, sessionId);
+					if (hasApiRemoteSubagentOwner(ctx, { header: inspected.meta }, void 0)) throw new ApiRemoteSubagentSessionOwnership(sessionId);
+					const setup = options.setup === void 0 ? void 0 : await options.setup(inspected);
+					const publishedSession = ctx.sessions.get(sessionId);
+					const publishedAgent = ctx.agents.get(sessionId);
+					if (publishedSession !== void 0 && hasApiRemoteSubagentOwner(ctx, publishedSession, publishedAgent)) throw new ApiRemoteSubagentSessionOwnership(sessionId);
+					return (await ctx.agents.resume({
+						resumeSessionId: sessionId,
+						...options.agentOptions === void 0 ? {} : { agentOptions: options.agentOptions() },
+						...setup === void 0 ? {} : { setup }
+					})).agent;
+				} finally {
+					resumes.delete(sessionId);
+				}
+			})();
+			resumes.set(sessionId, resume);
+		}
+		try {
+			return { agent: await resume };
+		} catch (error) {
+			if (error instanceof ApiRemoteSessionNotFound) return { error: {
+				code: "session-not-found",
+				message: error.message,
+				details: { sessionId }
+			} };
+			if (error instanceof ApiRemoteSubagentSessionOwnership) return { error: apiRemoteSubagentOwnershipError(error.sessionId) };
+			const fenced = fencedLiveAgent(sessionId);
+			if (fenced !== void 0) return fenced;
+			const attached = ctx.sessions.get(sessionId);
+			if (attached !== void 0 && hasApiRemoteSubagentOwner(ctx, attached, void 0)) return { error: apiRemoteSubagentOwnershipError(sessionId) };
+			return { error: {
+				code: "internal",
+				message: `resume failed for session "${sessionId}": ${String(error)}`,
+				details: {}
+			} };
+		}
+	};
+	ctx.inject(["typert"], (typeCtx) => {
+		const resolveAgent = async (sessionId) => {
+			const found = await agentFor(sessionId);
+			if ("error" in found) throw new TypeRTLookupFailure(found.error);
+			return found.agent;
+		};
+		typeCtx.typert.lookups.configure("agent", resolveAgent);
+		typeCtx.typert.lookups.configure("session", async (sessionId) => (await resolveAgent(sessionId)).session);
+		typeCtx.typert.contexts.configureHost("agent", async (sessionId) => (await resolveAgent(sessionId)).ctx);
+	});
+	return agentFor;
+}
+//#endregion
+//#region lib/types/index.js
+/** Host plugin body; the selected contributions mount only in Client environments. */
+function apply() {}
+//#endregion
+export { ApiRemoteSessionNotFound, ApiRemoteSubagentSessionOwnership, apiRemoteSubagentOwnershipError, apply, createApiRemoteAgentResolver, hasApiRemoteSubagentOwner, inspectApiRemoteSession };

package/lib/invariant.js

@@ -0,0 +1,17 @@
+//#region lib/types/invariant.js
+/** Package-owned invariant companion for `@deepseek-ai/dsh-api-remotes`. */
+const PACKAGE_NAME = "@deepseek-ai/dsh-api-remotes";
+/** Cordis companion plugin name. */
+const name = "api-remotes-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/** No runtime invariant: TypeRT and the Agent/Session registries own the observed relationships. */
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/agent-lookup.d.ts

@@ -0,0 +1,95 @@
+/** Host BFF policy for resolving Remote Agent and Session identities. */
+import type { Context } from '@deepseek-ai/cordis';
+import type { Agent, AgentOptions, AgentSetup } from '@deepseek-ai/dsh-agent';
+import type { Session, SessionEvent, SessionHeader, SessionId } from '@deepseek-ai/dsh-session';
+/** Caller-facing failures preserved by the Gateway's RPC adapter. */
+export type ApiRemoteLookupError = {
+    readonly code: 'agent-busy';
+    readonly message: string;
+    readonly details: {
+        readonly reason: string;
+    };
+} | {
+    readonly code: 'session-not-found';
+    readonly message: string;
+    readonly details: {
+        readonly sessionId: SessionId;
+    };
+} | {
+    readonly code: 'internal';
+    readonly message: string;
+    readonly details: Record<never, never>;
+};
+/** Result of resolving one session identity to its live Agent. */
+export type ApiRemoteAgentResult = {
+    readonly agent: Agent;
+} | {
+    readonly error: ApiRemoteLookupError;
+};
+/** Resume configuration supplied by the owning Host composition. */
+export interface ApiRemoteAgentOptions {
+    /** Read the per-Agent defaults when a cold identity must resume. */
+    readonly agentOptions?: () => AgentOptions;
+    /**
+     * Build the Host-specific Agent-scope composition completed before
+     * publication. Keyed by the resumed session itself because what a Host
+     * installs may depend on what that session recorded: an agent preset fixes
+     * the tools its history was produced under, so rebuilding it under another
+     * composition would replay tool calls the agent can no longer make. The
+     * events come along because a session's own record of such a choice may be
+     * an event rather than a header field.
+     * @param session - the resumed session's persisted header and event log.
+     * @returns the Agent-scope setup to run before publication.
+     */
+    readonly setup?: (session: {
+        meta: SessionHeader;
+        events: readonly SessionEvent[];
+    }) => AgentSetup | Promise<AgentSetup>;
+}
+/** Cold identity absent from the durable session store. */
+export declare class ApiRemoteSessionNotFound extends Error {
+}
+/** Session identity whose lifecycle belongs to subagent routing. */
+export declare class ApiRemoteSubagentSessionOwnership extends Error {
+    readonly sessionId: SessionId;
+    /**
+     * Construct the ownership fence.
+     * @param sessionId - identity reserved to subagent routing.
+     */
+    constructor(sessionId: SessionId);
+}
+/**
+ * Test whether generic Host routing must leave an identity to subagent routing.
+ * @param ctx - Host Context carrying the live Agent registry.
+ * @param session - attached or live Session metadata.
+ * @param agent - live Agent when one is registered.
+ * @returns whether generic Remote and legacy API calls must reject the identity.
+ */
+export declare function hasApiRemoteSubagentOwner(ctx: Context, session: Pick<Session, 'header'>, agent: Agent | undefined): boolean;
+/**
+ * Build the stable caller-facing ownership rejection.
+ * @param sessionId - identity reserved to subagent routing.
+ * @returns the existing `agent-busy` RPC shape.
+ */
+export declare function apiRemoteSubagentOwnershipError(sessionId: SessionId): ApiRemoteLookupError;
+/**
+ * Inspect one cold served session without repairing, resuming, or publishing it.
+ * @param ctx - Host Context carrying the optional persistence provider.
+ * @param sessionId - durable identity to inspect.
+ * @returns detached metadata and events for a servable session.
+ * @throws {@link ApiRemoteSessionNotFound} when the identity has no project-backed session.
+ */
+export declare function inspectApiRemoteSession(ctx: Context, sessionId: SessionId): Promise<{
+    meta: SessionHeader;
+    events: SessionEvent[];
+}>;
+/**
+ * Create the Host's shared Agent resolver and configure Agent/Session TypeRT lookups.
+ * Live Agents are reused, ordinary cold sessions resume once per identity, and
+ * subagent-owned identities retain the legacy `agent-busy` fence.
+ * @param ctx - owning Host Context.
+ * @param options - defaults and Agent-scope setup used only for cold resume.
+ * @returns resolver shared by legacy API Proxy methods and TypeRT lookups.
+ */
+export declare function createApiRemoteAgentResolver(ctx: Context, options: ApiRemoteAgentOptions): (sessionId: SessionId) => Promise<ApiRemoteAgentResult>;
+//# sourceMappingURL=agent-lookup.d.ts.map

package/lib/types/client/index.d.ts

@@ -0,0 +1,20 @@
+/** Platform-neutral assembly of generated Host Remote contributions. */
+import type { Context } from '@deepseek-ai/cordis';
+import type { TypeRTClientRemote } from '@deepseek-ai/dsh-type-meta';
+export type { TypeRTClientRemote as ClientRemote } from '@deepseek-ai/dsh-type-meta';
+export type {} from '@deepseek-ai/dsh-goal/remote';
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        /** Generated Remote namespaces selected by this Client assembly. */
+        remote: TypeRTClientRemote;
+    }
+}
+/** Required service: the typed Client Remote contribution mount. */
+export declare const inject: string[];
+/**
+ * Mount the Host capabilities explicitly selected for this Client assembly.
+ * @param ctx - Client Cordis root carrying the typed API service.
+ * @returns disposer after every selected Remote namespace is ready.
+ */
+export declare function apply(ctx: Context): Promise<() => Promise<void>>;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,6 @@
+/** Host BFF entry and Loader shell for the Remote contribution assembly. */
+export { ApiRemoteSessionNotFound, ApiRemoteSubagentSessionOwnership, apiRemoteSubagentOwnershipError, createApiRemoteAgentResolver, hasApiRemoteSubagentOwner, inspectApiRemoteSession, } from './agent-lookup.ts';
+export type { ApiRemoteAgentOptions, ApiRemoteAgentResult, ApiRemoteLookupError, } from './agent-lookup.ts';
+/** Host plugin body; the selected contributions mount only in Client environments. */
+export declare function apply(): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,13 @@
+/** Package-owned invariant companion for `@deepseek-ai/dsh-api-remotes`. */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "api-remotes-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@deepseek-ai/dsh-api-remotes",
+  "description": "Remote BFF assembly and Host Agent/Session lookup policy",
+  "version": "0.0.1-rc.1",
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/api/remotes"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "dsh": {
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-api-gateway"
+      ],
+      "platform": "web",
+      "immediately": true
+    }
+  },
+  "license": "BSD-3-Clause",
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/client.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "dependencies": {
+    "@deepseek-ai/dsh-type-meta": "^0.0.1-rc.1"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-agent": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-goal": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-session": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-session-persistence": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-typert-registry": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-agent": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-goal": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-session": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-session-persistence": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-typert-registry": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1"
+  },
+  "scripts": {
+    "bundle": "tsdown",
+    "watch": "tsdown --watch"
+  }
+}