@agimon-ai/doompi-core 0.0.1-alpha.100

package/dist/src/schemas/notification.mjs

@@ -0,0 +1,108 @@
+import { Type } from "typebox";
+import { Check } from "typebox/value";
+//#region src/schemas/notification.ts
+/** Provider-owned Cordis service for caller-authored notification requests. */
+const DOOM_NOTIFICATION_SERVICE = "doom/notification";
+/** Custom session entry type used to publish normalized notification data. */
+const DOOM_NOTIFICATION_ENTRY_TYPE = "doom-notification";
+const DOOM_NOTIFICATION_ENTRY_VERSION = 1;
+const MAX_DOOM_NOTIFICATION_TITLE_CHARACTERS = 128;
+const MAX_DOOM_NOTIFICATION_SUBTITLE_CHARACTERS = 256;
+const MAX_DOOM_NOTIFICATION_BODY_CHARACTERS = 4096;
+const DoomNotificationLevelSchema = Type.Union([
+	Type.Literal("info"),
+	Type.Literal("warning"),
+	Type.Literal("error")
+]);
+const DoomNotificationRequestSchema = Type.Object({
+	title: Type.Optional(Type.String({
+		minLength: 1,
+		maxLength: 128
+	})),
+	subtitle: Type.Optional(Type.String({
+		minLength: 1,
+		maxLength: 256
+	})),
+	body: Type.String({
+		minLength: 1,
+		maxLength: MAX_DOOM_NOTIFICATION_BODY_CHARACTERS
+	}),
+	level: Type.Optional(DoomNotificationLevelSchema)
+}, { additionalProperties: false });
+const NormalizableDoomNotificationRequestSchema = Type.Object({
+	title: Type.Optional(Type.String()),
+	subtitle: Type.Optional(Type.String()),
+	body: Type.String(),
+	level: Type.Optional(DoomNotificationLevelSchema)
+}, { additionalProperties: false });
+const DoomNotificationEntryDataSchema = Type.Object({
+	version: Type.Literal(1),
+	title: Type.String({ maxLength: 128 }),
+	subtitle: Type.String({ maxLength: 256 }),
+	body: Type.String({
+		minLength: 1,
+		maxLength: MAX_DOOM_NOTIFICATION_BODY_CHARACTERS
+	}),
+	level: DoomNotificationLevelSchema
+}, { additionalProperties: false });
+function replaceControlCharacters(text) {
+	return Array.from(text, (character) => {
+		const codePoint = character.codePointAt(0);
+		return codePoint !== void 0 && (codePoint < 32 || codePoint === 127) ? " " : character;
+	}).join("");
+}
+function normalizeText(text, maximum) {
+	const normalized = replaceControlCharacters(text).replace(/\s+/gu, " ").trim();
+	if (!normalized) return void 0;
+	let truncated = "";
+	for (const character of normalized) {
+		if (truncated.length + character.length > maximum) break;
+		truncated += character;
+	}
+	return truncated;
+}
+/** Normalize caller-owned notification text into a validated request. */
+function normalizeDoomNotificationRequest(request) {
+	if (!Check(NormalizableDoomNotificationRequestSchema, request)) return void 0;
+	const body = normalizeText(request.body, MAX_DOOM_NOTIFICATION_BODY_CHARACTERS);
+	if (!body) return void 0;
+	const title = request.title && normalizeText(request.title, 128);
+	const subtitle = request.subtitle && normalizeText(request.subtitle, 256);
+	const normalized = {
+		body,
+		...title ? { title } : {},
+		...subtitle ? { subtitle } : {},
+		...request.level ? { level: request.level } : {}
+	};
+	return Object.freeze(normalized);
+}
+/** Builds normalized, versioned data for a Doom notification session entry. */
+function createDoomNotificationEntryData(request) {
+	const normalized = normalizeDoomNotificationRequest(request);
+	if (!normalized) return void 0;
+	return Object.freeze({
+		version: 1,
+		title: normalized.title ?? "",
+		subtitle: normalized.subtitle ?? "",
+		body: normalized.body,
+		level: normalized.level ?? "info"
+	});
+}
+function isDoomNotificationRequest(value) {
+	return Check(DoomNotificationRequestSchema, value);
+}
+function isDoomNotificationEntryData(value) {
+	return Check(DoomNotificationEntryDataSchema, value);
+}
+function readDoomNotificationService(context) {
+	return context.get(DOOM_NOTIFICATION_SERVICE);
+}
+function requireDoomNotificationService(context) {
+	const service = readDoomNotificationService(context);
+	if (!service) throw new Error("Doom notification is unavailable. Load a notification provider.");
+	return service;
+}
+//#endregion
+export { DOOM_NOTIFICATION_ENTRY_TYPE, DOOM_NOTIFICATION_ENTRY_VERSION, DOOM_NOTIFICATION_SERVICE, DoomNotificationEntryDataSchema, DoomNotificationLevelSchema, DoomNotificationRequestSchema, MAX_DOOM_NOTIFICATION_BODY_CHARACTERS, MAX_DOOM_NOTIFICATION_SUBTITLE_CHARACTERS, MAX_DOOM_NOTIFICATION_TITLE_CHARACTERS, createDoomNotificationEntryData, isDoomNotificationEntryData, isDoomNotificationRequest, normalizeDoomNotificationRequest, readDoomNotificationService, requireDoomNotificationService };
+
+//# sourceMappingURL=notification.mjs.map

package/dist/src/schemas/notification.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"notification.mjs","names":[],"sources":["../../../src/schemas/notification.ts"],"sourcesContent":["import type { Context } from '@deepseek-ai/cordis';\nimport { type Static, Type } from 'typebox';\nimport { Check } from 'typebox/value';\n\n/** Provider-owned Cordis service for caller-authored notification requests. */\nexport const DOOM_NOTIFICATION_SERVICE = 'doom/notification';\n/** Custom session entry type used to publish normalized notification data. */\nexport const DOOM_NOTIFICATION_ENTRY_TYPE = 'doom-notification';\nexport const DOOM_NOTIFICATION_ENTRY_VERSION = 1 as const;\nexport const MAX_DOOM_NOTIFICATION_TITLE_CHARACTERS = 128;\nexport const MAX_DOOM_NOTIFICATION_SUBTITLE_CHARACTERS = 256;\nexport const MAX_DOOM_NOTIFICATION_BODY_CHARACTERS = 4_096;\n\nexport const DoomNotificationLevelSchema = Type.Union([\n  Type.Literal('info'),\n  Type.Literal('warning'),\n  Type.Literal('error'),\n]);\nexport type DoomNotificationLevel = Static<typeof DoomNotificationLevelSchema>;\n\nexport const DoomNotificationRequestSchema = Type.Object(\n  {\n    title: Type.Optional(Type.String({ minLength: 1, maxLength: MAX_DOOM_NOTIFICATION_TITLE_CHARACTERS })),\n    subtitle: Type.Optional(Type.String({ minLength: 1, maxLength: MAX_DOOM_NOTIFICATION_SUBTITLE_CHARACTERS })),\n    body: Type.String({ minLength: 1, maxLength: MAX_DOOM_NOTIFICATION_BODY_CHARACTERS }),\n    level: Type.Optional(DoomNotificationLevelSchema),\n  },\n  { additionalProperties: false },\n);\nexport type DoomNotificationRequest = Static<typeof DoomNotificationRequestSchema>;\n\nconst NormalizableDoomNotificationRequestSchema = Type.Object(\n  {\n    title: Type.Optional(Type.String()),\n    subtitle: Type.Optional(Type.String()),\n    body: Type.String(),\n    level: Type.Optional(DoomNotificationLevelSchema),\n  },\n  { additionalProperties: false },\n);\n\nexport const DoomNotificationEntryDataSchema = Type.Object(\n  {\n    version: Type.Literal(DOOM_NOTIFICATION_ENTRY_VERSION),\n    title: Type.String({ maxLength: MAX_DOOM_NOTIFICATION_TITLE_CHARACTERS }),\n    subtitle: Type.String({ maxLength: MAX_DOOM_NOTIFICATION_SUBTITLE_CHARACTERS }),\n    body: Type.String({ minLength: 1, maxLength: MAX_DOOM_NOTIFICATION_BODY_CHARACTERS }),\n    level: DoomNotificationLevelSchema,\n  },\n  { additionalProperties: false },\n);\nexport type DoomNotificationEntryData = Static<typeof DoomNotificationEntryDataSchema>;\n\n/** Generic outbound notification seam. The provider owns delivery and lifecycle. */\nexport interface DoomNotificationService {\n  readonly generation: string;\n  request(request: DoomNotificationRequest): void | Promise<void>;\n}\n\ndeclare module '@deepseek-ai/cordis' {\n  interface Context {\n    'doom/notification': DoomNotificationService;\n  }\n}\n\nfunction replaceControlCharacters(text: string): string {\n  return Array.from(text, (character) => {\n    const codePoint = character.codePointAt(0);\n    return codePoint !== undefined && (codePoint < 0x20 || codePoint === 0x7f) ? ' ' : character;\n  }).join('');\n}\n\nfunction normalizeText(text: string, maximum: number): string | undefined {\n  const normalized = replaceControlCharacters(text).replace(/\\s+/gu, ' ').trim();\n  if (!normalized) return undefined;\n\n  let truncated = '';\n  for (const character of normalized) {\n    if (truncated.length + character.length > maximum) break;\n    truncated += character;\n  }\n  return truncated;\n}\n\n/** Normalize caller-owned notification text into a validated request. */\nexport function normalizeDoomNotificationRequest(request: unknown): DoomNotificationRequest | undefined {\n  if (!Check(NormalizableDoomNotificationRequestSchema, request)) return undefined;\n\n  const body = normalizeText(request.body, MAX_DOOM_NOTIFICATION_BODY_CHARACTERS);\n  if (!body) return undefined;\n  const title = request.title && normalizeText(request.title, MAX_DOOM_NOTIFICATION_TITLE_CHARACTERS);\n  const subtitle = request.subtitle && normalizeText(request.subtitle, MAX_DOOM_NOTIFICATION_SUBTITLE_CHARACTERS);\n  const normalized = {\n    body,\n    ...(title ? { title } : {}),\n    ...(subtitle ? { subtitle } : {}),\n    ...(request.level ? { level: request.level } : {}),\n  };\n  return Object.freeze(normalized);\n}\n\n/** Builds normalized, versioned data for a Doom notification session entry. */\nexport function createDoomNotificationEntryData(request: unknown): DoomNotificationEntryData | undefined {\n  const normalized = normalizeDoomNotificationRequest(request);\n  if (!normalized) return undefined;\n  return Object.freeze({\n    version: DOOM_NOTIFICATION_ENTRY_VERSION,\n    title: normalized.title ?? '',\n    subtitle: normalized.subtitle ?? '',\n    body: normalized.body,\n    level: normalized.level ?? 'info',\n  });\n}\n\nexport function isDoomNotificationRequest(value: unknown): value is DoomNotificationRequest {\n  return Check(DoomNotificationRequestSchema, value);\n}\n\nexport function isDoomNotificationEntryData(value: unknown): value is DoomNotificationEntryData {\n  return Check(DoomNotificationEntryDataSchema, value);\n}\n\nexport function readDoomNotificationService(context: Context): DoomNotificationService | undefined {\n  return context.get(DOOM_NOTIFICATION_SERVICE) as DoomNotificationService | undefined;\n}\n\nexport function requireDoomNotificationService(context: Context): DoomNotificationService {\n  const service = readDoomNotificationService(context);\n  if (!service) throw new Error('Doom notification is unavailable. Load a notification provider.');\n  return service;\n}\n"],"mappings":";;;;AAKA,MAAa,4BAA4B;;AAEzC,MAAa,+BAA+B;AAC5C,MAAa,kCAAkC;AAC/C,MAAa,yCAAyC;AACtD,MAAa,4CAA4C;AACzD,MAAa,wCAAwC;AAErD,MAAa,8BAA8B,KAAK,MAAM;CACpD,KAAK,QAAQ,MAAM;CACnB,KAAK,QAAQ,SAAS;CACtB,KAAK,QAAQ,OAAO;AACtB,CAAC;AAGD,MAAa,gCAAgC,KAAK,OAChD;CACE,OAAO,KAAK,SAAS,KAAK,OAAO;EAAE,WAAW;EAAG,WAAA;CAAkD,CAAC,CAAC;CACrG,UAAU,KAAK,SAAS,KAAK,OAAO;EAAE,WAAW;EAAG,WAAA;CAAqD,CAAC,CAAC;CAC3G,MAAM,KAAK,OAAO;EAAE,WAAW;EAAG,WAAW;CAAsC,CAAC;CACpF,OAAO,KAAK,SAAS,2BAA2B;AAClD,GACA,EAAE,sBAAsB,MAAM,CAChC;AAGA,MAAM,4CAA4C,KAAK,OACrD;CACE,OAAO,KAAK,SAAS,KAAK,OAAO,CAAC;CAClC,UAAU,KAAK,SAAS,KAAK,OAAO,CAAC;CACrC,MAAM,KAAK,OAAO;CAClB,OAAO,KAAK,SAAS,2BAA2B;AAClD,GACA,EAAE,sBAAsB,MAAM,CAChC;AAEA,MAAa,kCAAkC,KAAK,OAClD;CACE,SAAS,KAAK,QAAA,CAAuC;CACrD,OAAO,KAAK,OAAO,EAAE,WAAA,IAAkD,CAAC;CACxE,UAAU,KAAK,OAAO,EAAE,WAAA,IAAqD,CAAC;CAC9E,MAAM,KAAK,OAAO;EAAE,WAAW;EAAG,WAAW;CAAsC,CAAC;CACpF,OAAO;AACT,GACA,EAAE,sBAAsB,MAAM,CAChC;AAeA,SAAS,yBAAyB,MAAsB;CACtD,OAAO,MAAM,KAAK,OAAO,cAAc;EACrC,MAAM,YAAY,UAAU,YAAY,CAAC;EACzC,OAAO,cAAc,KAAA,MAAc,YAAY,MAAQ,cAAc,OAAQ,MAAM;CACrF,CAAC,CAAC,CAAC,KAAK,EAAE;AACZ;AAEA,SAAS,cAAc,MAAc,SAAqC;CACxE,MAAM,aAAa,yBAAyB,IAAI,CAAC,CAAC,QAAQ,SAAS,GAAG,CAAC,CAAC,KAAK;CAC7E,IAAI,CAAC,YAAY,OAAO,KAAA;CAExB,IAAI,YAAY;CAChB,KAAK,MAAM,aAAa,YAAY;EAClC,IAAI,UAAU,SAAS,UAAU,SAAS,SAAS;EACnD,aAAa;CACf;CACA,OAAO;AACT;;AAGA,SAAgB,iCAAiC,SAAuD;CACtG,IAAI,CAAC,MAAM,2CAA2C,OAAO,GAAG,OAAO,KAAA;CAEvE,MAAM,OAAO,cAAc,QAAQ,MAAM,qCAAqC;CAC9E,IAAI,CAAC,MAAM,OAAO,KAAA;CAClB,MAAM,QAAQ,QAAQ,SAAS,cAAc,QAAQ,OAAA,GAA6C;CAClG,MAAM,WAAW,QAAQ,YAAY,cAAc,QAAQ,UAAA,GAAmD;CAC9G,MAAM,aAAa;EACjB;EACA,GAAI,QAAQ,EAAE,MAAM,IAAI,CAAC;EACzB,GAAI,WAAW,EAAE,SAAS,IAAI,CAAC;EAC/B,GAAI,QAAQ,QAAQ,EAAE,OAAO,QAAQ,MAAM,IAAI,CAAC;CAClD;CACA,OAAO,OAAO,OAAO,UAAU;AACjC;;AAGA,SAAgB,gCAAgC,SAAyD;CACvG,MAAM,aAAa,iCAAiC,OAAO;CAC3D,IAAI,CAAC,YAAY,OAAO,KAAA;CACxB,OAAO,OAAO,OAAO;EACnB,SAAA;EACA,OAAO,WAAW,SAAS;EAC3B,UAAU,WAAW,YAAY;EACjC,MAAM,WAAW;EACjB,OAAO,WAAW,SAAS;CAC7B,CAAC;AACH;AAEA,SAAgB,0BAA0B,OAAkD;CAC1F,OAAO,MAAM,+BAA+B,KAAK;AACnD;AAEA,SAAgB,4BAA4B,OAAoD;CAC9F,OAAO,MAAM,iCAAiC,KAAK;AACrD;AAEA,SAAgB,4BAA4B,SAAuD;CACjG,OAAO,QAAQ,IAAI,yBAAyB;AAC9C;AAEA,SAAgB,+BAA+B,SAA2C;CACxF,MAAM,UAAU,4BAA4B,OAAO;CACnD,IAAI,CAAC,SAAS,MAAM,IAAI,MAAM,iEAAiE;CAC/F,OAAO;AACT"}

package/dist/src/schemas/packageApi.cjs

@@ -0,0 +1,73 @@
+//#region src/schemas/packageApi.ts
+const DOOM_API_SCOPES = [
+	"global",
+	"workspace",
+	"session"
+];
+/** Canonical public prefix. Scope selection never falls through to a parent. */
+function doomApiMountPath(mount) {
+	if (mount.scope === "global") return "/api/plugins";
+	if (mount.scope === "workspace") return `/api/workspaces/${encodeURIComponent(mount.workspaceId)}/plugins`;
+	if (!mount.workspaceId) throw new Error("A session API path requires its workspace identity.");
+	return `/api/workspaces/${encodeURIComponent(mount.workspaceId)}/sessions/${encodeURIComponent(mount.sessionId)}/plugins`;
+}
+/** Only canonical resource paths may select a protocol listener. */
+function parseDoomSocketPath(pathname) {
+	if (pathname === "/api/ws") return { scope: "global" };
+	const match = /^\/api\/workspaces\/([^/]+)(?:\/sessions\/([^/]+))?\/ws$/u.exec(pathname);
+	if (!match) return void 0;
+	try {
+		const workspaceId = decodeURIComponent(match[1]);
+		return match[2] === void 0 ? {
+			scope: "workspace",
+			workspaceId
+		} : {
+			scope: "session",
+			workspaceId,
+			sessionId: decodeURIComponent(match[2])
+		};
+	} catch {
+		return;
+	}
+}
+/** The segment an API is mounted under, below this prefix. */
+const DOOM_API_ROUTE_PREFIX = "/api/plugins";
+/** Selects the hub API bundle that owns the named cockpit session. */
+const DOOM_HUB_API_SESSION_QUERY_PARAM = "hubSession";
+/** Trusted caller headers written only by the cockpit-to-session proxy. */
+const DOOM_API_CALLER_LOCALITY_HEADER = "x-doompi-api-caller-locality";
+const DOOM_API_CALLER_DEVICE_ID_HEADER = "x-doompi-api-caller-device-id";
+const DOOM_API_CALLER_STEP_UP_HEADER = "x-doompi-api-caller-step-up";
+const DOOM_API_CALLER_HEADERS = [
+	DOOM_API_CALLER_LOCALITY_HEADER,
+	DOOM_API_CALLER_DEVICE_ID_HEADER,
+	DOOM_API_CALLER_STEP_UP_HEADER
+];
+/** Reads the proxy-authenticated caller identity, rejecting partial or contradictory stamps. */
+function doomApiCallerFrom(headers) {
+	const locality = headers.get(DOOM_API_CALLER_LOCALITY_HEADER);
+	const deviceId = headers.get(DOOM_API_CALLER_DEVICE_ID_HEADER);
+	const stepUp = headers.get(DOOM_API_CALLER_STEP_UP_HEADER);
+	if (locality === "local") return deviceId === null && stepUp === "not-required" ? {
+		locality,
+		stepUp
+	} : void 0;
+	if (locality === "remote" && deviceId !== null && deviceId !== "" && (stepUp === "not-required" || stepUp === "verified" || stepUp === "unavailable")) return {
+		locality,
+		deviceId,
+		stepUp
+	};
+}
+//#endregion
+exports.DOOM_API_CALLER_DEVICE_ID_HEADER = DOOM_API_CALLER_DEVICE_ID_HEADER;
+exports.DOOM_API_CALLER_HEADERS = DOOM_API_CALLER_HEADERS;
+exports.DOOM_API_CALLER_LOCALITY_HEADER = DOOM_API_CALLER_LOCALITY_HEADER;
+exports.DOOM_API_CALLER_STEP_UP_HEADER = DOOM_API_CALLER_STEP_UP_HEADER;
+exports.DOOM_API_ROUTE_PREFIX = DOOM_API_ROUTE_PREFIX;
+exports.DOOM_API_SCOPES = DOOM_API_SCOPES;
+exports.DOOM_HUB_API_SESSION_QUERY_PARAM = DOOM_HUB_API_SESSION_QUERY_PARAM;
+exports.doomApiCallerFrom = doomApiCallerFrom;
+exports.doomApiMountPath = doomApiMountPath;
+exports.parseDoomSocketPath = parseDoomSocketPath;
+
+//# sourceMappingURL=packageApi.cjs.map

package/dist/src/schemas/packageApi.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"packageApi.cjs","names":[],"sources":["../../../src/schemas/packageApi.ts"],"sourcesContent":["/**\n * The HTTP surface a package offers its host.\n *\n * A server facet registers one with its host. The host mounts it under the API\n * route prefix, and the package writes routes relative to that mount.\n *\n * The handler is a plain fetch callback so no host and no package is committed\n * to one HTTP framework; a Hono app satisfies it through `app.fetch`.\n */\n\nimport type {\n  DoomComputerUseSessionAccess,\n  DoomDirectEventBus,\n  DoomHubSessionService,\n  DoomSessionCommunicationEndpoint,\n  DoomSessionContext,\n} from './hubChannel';\nimport type { DoomMcpProjection } from './mcpProjection';\n/** The host-owned sync view a repository-scoped package API may inspect. */\nexport interface DoomRepositorySyncView {\n  fresh: boolean;\n  reasons: string[];\n  mcpProjection?: DoomMcpProjection;\n}\n\n/** Where an API runs: inside one session's server, or in the machine-wide hub. */\nexport type DoomApiScope = 'global' | 'workspace' | 'session';\n\nexport const DOOM_API_SCOPES: readonly DoomApiScope[] = ['global', 'workspace', 'session'];\n\n/** Identity of an independently mounted plugin host. */\nexport type DoomApiMount =\n  | { scope: 'global' }\n  | { scope: 'workspace'; workspaceId: string }\n  | { scope: 'session'; sessionId: string };\n\n/** Immutable browser contribution generation paired with a server mount. */\nexport interface DoomWebComposition {\n  id: string;\n  scope: DoomApiScope;\n  revision: number;\n  manifestUrl: string;\n  rawAssetBaseUrl: string;\n  verifiedAssetBaseUrl: string;\n  entryPath: string;\n  stylePaths: string[];\n  channels: string[];\n}\n\n/** Canonical public prefix. Scope selection never falls through to a parent. */\nexport function doomApiMountPath(mount: DoomApiMount & { workspaceId?: string }): string {\n  if (mount.scope === 'global') return '/api/plugins';\n  if (mount.scope === 'workspace') return `/api/workspaces/${encodeURIComponent(mount.workspaceId)}/plugins`;\n  if (!mount.workspaceId) throw new Error('A session API path requires its workspace identity.');\n  return `/api/workspaces/${encodeURIComponent(mount.workspaceId)}/sessions/${encodeURIComponent(mount.sessionId)}/plugins`;\n}\n\n/** Scope addressed by a public WebSocket upgrade. */\nexport type DoomSocketMount =\n  | { scope: 'global' }\n  | { scope: 'workspace'; workspaceId: string }\n  | { scope: 'session'; workspaceId: string; sessionId: string };\n\n/** Only canonical resource paths may select a protocol listener. */\nexport function parseDoomSocketPath(pathname: string): DoomSocketMount | undefined {\n  if (pathname === '/api/ws') return { scope: 'global' };\n  const match = /^\\/api\\/workspaces\\/([^/]+)(?:\\/sessions\\/([^/]+))?\\/ws$/u.exec(pathname);\n  if (!match) return undefined;\n  try {\n    const workspaceId = decodeURIComponent(match[1]);\n    return match[2] === undefined\n      ? { scope: 'workspace', workspaceId }\n      : { scope: 'session', workspaceId, sessionId: decodeURIComponent(match[2]) };\n  } catch {\n    return undefined;\n  }\n}\n\n/** The segment an API is mounted under, below this prefix. */\nexport const DOOM_API_ROUTE_PREFIX = '/api/plugins';\n/** Selects the hub API bundle that owns the named cockpit session. */\nexport const DOOM_HUB_API_SESSION_QUERY_PARAM = 'hubSession';\n\n/** Trusted caller headers written only by the cockpit-to-session proxy. */\nexport const DOOM_API_CALLER_LOCALITY_HEADER = 'x-doompi-api-caller-locality';\nexport const DOOM_API_CALLER_DEVICE_ID_HEADER = 'x-doompi-api-caller-device-id';\nexport const DOOM_API_CALLER_STEP_UP_HEADER = 'x-doompi-api-caller-step-up';\nexport const DOOM_API_CALLER_HEADERS = [\n  DOOM_API_CALLER_LOCALITY_HEADER,\n  DOOM_API_CALLER_DEVICE_ID_HEADER,\n  DOOM_API_CALLER_STEP_UP_HEADER,\n] as const;\n\nexport type DoomApiCallerStepUp = 'not-required' | 'verified' | 'unavailable';\nexport type DoomApiCaller =\n  | { locality: 'local'; stepUp: 'not-required' }\n  | { locality: 'remote'; deviceId: string; stepUp: DoomApiCallerStepUp };\n\n/** Reads the proxy-authenticated caller identity, rejecting partial or contradictory stamps. */\nexport function doomApiCallerFrom(headers: Headers): DoomApiCaller | undefined {\n  const locality = headers.get(DOOM_API_CALLER_LOCALITY_HEADER);\n  const deviceId = headers.get(DOOM_API_CALLER_DEVICE_ID_HEADER);\n  const stepUp = headers.get(DOOM_API_CALLER_STEP_UP_HEADER);\n  if (locality === 'local') {\n    return deviceId === null && stepUp === 'not-required' ? { locality, stepUp } : undefined;\n  }\n  if (\n    locality === 'remote' &&\n    deviceId !== null &&\n    deviceId !== '' &&\n    (stepUp === 'not-required' || stepUp === 'verified' || stepUp === 'unavailable')\n  ) {\n    return { locality, deviceId, stepUp };\n  }\n  return undefined;\n}\n/**\n * A browser-reachable OAuth redirect the host serves on its own listener.\n *\n * A package brokering third-party OAuth cannot use a loopback redirect when the\n * operator's browser is on another machine: `127.0.0.1` resolves to whichever\n * machine the browser runs on. The host owns a listener that is reachable from\n * wherever the cockpit is being used, so it lends that instead of the package\n * opening a port of its own.\n */\nexport interface DoomOAuthRedirect {\n  /** Absolute URL to register as the redirect target, already origin-correct. */\n  readonly redirectUri: string;\n  /**\n   * Accept redirects carrying this state. Must complete before the\n   * authorization URL is surfaced, or the redirect races its own reservation.\n   */\n  reserve(state: string, timeoutMs?: number): Promise<void>;\n  /** Resolves once the redirect carrying this state arrives. */\n  wait(state: string, timeoutMs?: number): Promise<{ code: string; state: string }>;\n  /** Drops a reservation whose flow ended without a redirect. */\n  cancel(state: string): void;\n}\n\n/** An exact, host-owned receipt address. Provider IDs are not event cursor positions. */\nexport interface DoomRequestReceiptKey {\n  namespace: string;\n  activationId: string;\n  requestId: string;\n}\n\nexport interface DoomRequestReceipt extends DoomRequestReceiptKey {\n  fingerprint: string;\n  destination: string;\n  transactionId: string;\n  outcome: 'reserved' | 'admitted' | 'rejected' | 'uncertain';\n}\n\nexport interface DoomRequestReceiptReservation extends DoomRequestReceiptKey {\n  /** Lowercase SHA-256 of the authoritative request text, never the full transcript. */\n  fingerprint: string;\n  destination: string;\n  transactionId: string;\n}\n\nexport type DoomRequestReceiptReserveResult =\n  | { kind: 'reserved'; token: string }\n  | { kind: 'existing'; receipt: DoomRequestReceipt }\n  | { kind: 'conflict'; receipt: DoomRequestReceipt };\n\n/** A global-only receipt capability. A reservation is not an execution receipt. */\nexport interface DoomRequestReceipts {\n  reserve(request: DoomRequestReceiptReservation): Promise<DoomRequestReceiptReserveResult>;\n  lookup(key: DoomRequestReceiptKey): Promise<DoomRequestReceipt | undefined>;\n  finish(\n    request: DoomRequestReceiptKey & { token: string; outcome: 'admitted' | 'rejected' | 'uncertain' },\n  ): Promise<DoomRequestReceipt>;\n}\n\n/** Permit returned for expensive local work. Calling it releases the slot. */\nexport interface DoomHostExecutionPermit {\n  (): void;\n  attachProcess?(pid: number): Promise<void>;\n}\n\n/** Host-wide admission for expensive local work. Release only after the owned process exits. */\nexport interface DoomHostExecutionBudget {\n  acquire(signal?: AbortSignal): Promise<DoomHostExecutionPermit>;\n  getSnapshot(): Readonly<{ running: number; queued: number; limit: number }>;\n}\n\n/** Synchronous host-owned exclusion across media APIs mounted at different scopes. */\nexport interface DoomHostMediaArbitration {\n  register(busy: () => boolean): () => void;\n  available(busy: () => boolean): boolean;\n}\n\n/** One host's paired agent registrations, shared across its global and session mounts. */\nexport interface DoomPeerAgentRegistry {\n  register(sessionId: string, agent: { fetch(request: Request): Promise<Response> }, hubToken: string): () => void;\n  get(sessionId: string): { fetch(request: Request): Promise<Response>; hubToken: string } | undefined;\n}\n\n/** What the host tells an API about itself when it starts. */\nexport interface DoomApiContext {\n  scope: DoomApiScope;\n  /** Stable, opaque workspace id, shared by every session and member checkout of the workspace. */\n  workspaceId?: string;\n  /**\n   * The admitted workspace root for a workspace mount. For a session mount it is the checkout\n   * the session runs in; read sessionContext for both roots. Absent from global mounts.\n   */\n  workspaceRoot?: string;\n  /** The session's baseline context; present on session mounts whose host knows its workspace. */\n  sessionContext?: DoomSessionContext;\n  /** Explicit host home, never selected by a remote request. */\n  homeDirectory?: string;\n  /** The session this host serves; absent for a hub-scoped API. */\n  sessionId?: string;\n  /** The session's working directory; absent for a hub-scoped API. */\n  cwd?: string;\n  /** Session environment admitted by the server, never supplied by remote clients. */\n  environment?: Readonly<Record<string, string | undefined>>;\n  /** Shared only with child processes in this session, never with remote API clients. */\n  internalToken?: string;\n  /** Shared only with the cockpit hub for privileged cross-session coordination. */\n  hubToken?: string;\n  /**\n   * Resolves a hub-issued opaque repository id to an admitted canonical root.\n   * Hub APIs must never accept a browser-supplied filesystem path instead.\n   */\n  resolveRepository?(repositoryId: string): string | undefined;\n  /** Reads the admitted repository's sync projection without exposing its state path. */\n  readRepositorySync?(repositoryId: string): DoomRepositorySyncView | undefined;\n  /** Admitted workspaces available to this mount. */\n  repositories?(): readonly { id: string; name: string; path: string; active: boolean }[];\n  /** Publish a successful config write to the owning mount's refresh lifecycle. */\n  configurationChanged?(): void;\n  /**\n   * Borrows the hub's OAuth redirect surface. Undefined when the hub cannot\n   * currently serve one, in which case the package keeps its own behaviour.\n   */\n  oauthRedirect?(): DoomOAuthRedirect | undefined;\n  /** Canonical in-process lifecycle for sessions created by this host. */\n  sessionService?: DoomHubSessionService;\n  /** Host-bound, authenticated inter-session event endpoint for this session. */\n  sessionCommunication?: DoomSessionCommunicationEndpoint;\n  /** Same-process events shared by session APIs and hub channels. */\n  directEvents?: DoomDirectEventBus;\n  /** Trusted in-process dispatch to an explicitly selected mounted API. No browser authentication is performed here. */\n  requestApi?(mount: DoomApiMount, basePath: string, request: Request): Promise<Response>;\n  /** Present only on a session mounted by an authenticated Desktop host. */\n  computerUse?: DoomComputerUseSessionAccess;\n  /** Deliver a typed method to a channel on this exact hub mount, retaining the caller's connection identity. */\n  receiveChannel?(sessionId: string, frameType: string, payload: unknown, connectionId: string): boolean;\n  /** Host-owned replay evidence, supplied only on the global mount. Never exposed to browsers or agents. */\n  requestReceipts?: DoomRequestReceipts;\n  /** One host's exclusive media activity, shared across global and session scopes. */\n  mediaArbitration?: DoomHostMediaArbitration;\n  /** One host-wide heavy-job budget, not a separate budget for every session. */\n  executionBudget?: DoomHostExecutionBudget;\n  /** Paired agents belonging to this host only. */\n  peerAgents?: DoomPeerAgentRegistry;\n  /** Machine-owned Remote Control service, mounted only by the global core facet. */\n  remoteControl?: { fetch(request: Request): Promise<Response> };\n  onNotice(message: string): void;\n}\n\n/**\n * One running surface. The host strips the mount prefix before calling, so\n * routes are declared relative ('/runners/:id/log') and a package never\n * repeats where it was mounted.\n */\nexport interface DoomApiHandler {\n  fetch(request: Request): Response | Promise<Response>;\n  close(): void;\n}\n\nexport interface DoomApi {\n  /** Segment under /api/plugins/; globally unique across loaded packages. */\n  basePath: string;\n  start(context: DoomApiContext): DoomApiHandler;\n}\n"],"mappings":";AA4BA,MAAa,kBAA2C;CAAC;CAAU;CAAa;AAAS;;AAsBzF,SAAgB,iBAAiB,OAAwD;CACvF,IAAI,MAAM,UAAU,UAAU,OAAO;CACrC,IAAI,MAAM,UAAU,aAAa,OAAO,mBAAmB,mBAAmB,MAAM,WAAW,EAAE;CACjG,IAAI,CAAC,MAAM,aAAa,MAAM,IAAI,MAAM,qDAAqD;CAC7F,OAAO,mBAAmB,mBAAmB,MAAM,WAAW,EAAE,YAAY,mBAAmB,MAAM,SAAS,EAAE;AAClH;;AASA,SAAgB,oBAAoB,UAA+C;CACjF,IAAI,aAAa,WAAW,OAAO,EAAE,OAAO,SAAS;CACrD,MAAM,QAAQ,4DAA4D,KAAK,QAAQ;CACvF,IAAI,CAAC,OAAO,OAAO,KAAA;CACnB,IAAI;EACF,MAAM,cAAc,mBAAmB,MAAM,EAAE;EAC/C,OAAO,MAAM,OAAO,KAAA,IAChB;GAAE,OAAO;GAAa;EAAY,IAClC;GAAE,OAAO;GAAW;GAAa,WAAW,mBAAmB,MAAM,EAAE;EAAE;CAC/E,QAAQ;EACN;CACF;AACF;;AAGA,MAAa,wBAAwB;;AAErC,MAAa,mCAAmC;;AAGhD,MAAa,kCAAkC;AAC/C,MAAa,mCAAmC;AAChD,MAAa,iCAAiC;AAC9C,MAAa,0BAA0B;CACrC;CACA;CACA;AACF;;AAQA,SAAgB,kBAAkB,SAA6C;CAC7E,MAAM,WAAW,QAAQ,IAAI,+BAA+B;CAC5D,MAAM,WAAW,QAAQ,IAAI,gCAAgC;CAC7D,MAAM,SAAS,QAAQ,IAAI,8BAA8B;CACzD,IAAI,aAAa,SACf,OAAO,aAAa,QAAQ,WAAW,iBAAiB;EAAE;EAAU;CAAO,IAAI,KAAA;CAEjF,IACE,aAAa,YACb,aAAa,QACb,aAAa,OACZ,WAAW,kBAAkB,WAAW,cAAc,WAAW,gBAElE,OAAO;EAAE;EAAU;EAAU;CAAO;AAGxC"}

package/dist/src/schemas/packageApi.d.mts

@@ -0,0 +1,249 @@
+import { DoomComputerUseSessionAccess, DoomDirectEventBus, DoomHubSessionService, DoomSessionCommunicationEndpoint, DoomSessionContext } from "./hubChannel.mjs";
+import { DoomMcpProjection } from "./mcpProjection.mjs";
+//#region src/schemas/packageApi.d.ts
+/** The host-owned sync view a repository-scoped package API may inspect. */
+export interface DoomRepositorySyncView {
+  fresh: boolean;
+  reasons: string[];
+  mcpProjection?: DoomMcpProjection;
+}
+/** Where an API runs: inside one session's server, or in the machine-wide hub. */
+export type DoomApiScope = 'global' | 'workspace' | 'session';
+export declare const DOOM_API_SCOPES: readonly DoomApiScope[];
+/** Identity of an independently mounted plugin host. */
+export type DoomApiMount = {
+  scope: 'global';
+} | {
+  scope: 'workspace';
+  workspaceId: string;
+} | {
+  scope: 'session';
+  sessionId: string;
+};
+/** Immutable browser contribution generation paired with a server mount. */
+export interface DoomWebComposition {
+  id: string;
+  scope: DoomApiScope;
+  revision: number;
+  manifestUrl: string;
+  rawAssetBaseUrl: string;
+  verifiedAssetBaseUrl: string;
+  entryPath: string;
+  stylePaths: string[];
+  channels: string[];
+}
+/** Canonical public prefix. Scope selection never falls through to a parent. */
+export declare function doomApiMountPath(mount: DoomApiMount & {
+  workspaceId?: string;
+}): string;
+/** Scope addressed by a public WebSocket upgrade. */
+export type DoomSocketMount = {
+  scope: 'global';
+} | {
+  scope: 'workspace';
+  workspaceId: string;
+} | {
+  scope: 'session';
+  workspaceId: string;
+  sessionId: string;
+};
+/** Only canonical resource paths may select a protocol listener. */
+export declare function parseDoomSocketPath(pathname: string): DoomSocketMount | undefined;
+/** The segment an API is mounted under, below this prefix. */
+export declare const DOOM_API_ROUTE_PREFIX = "/api/plugins";
+/** Selects the hub API bundle that owns the named cockpit session. */
+export declare const DOOM_HUB_API_SESSION_QUERY_PARAM = "hubSession";
+/** Trusted caller headers written only by the cockpit-to-session proxy. */
+export declare const DOOM_API_CALLER_LOCALITY_HEADER = "x-doompi-api-caller-locality";
+export declare const DOOM_API_CALLER_DEVICE_ID_HEADER = "x-doompi-api-caller-device-id";
+export declare const DOOM_API_CALLER_STEP_UP_HEADER = "x-doompi-api-caller-step-up";
+export declare const DOOM_API_CALLER_HEADERS: readonly ["x-doompi-api-caller-locality", "x-doompi-api-caller-device-id", "x-doompi-api-caller-step-up"];
+export type DoomApiCallerStepUp = 'not-required' | 'verified' | 'unavailable';
+export type DoomApiCaller = {
+  locality: 'local';
+  stepUp: 'not-required';
+} | {
+  locality: 'remote';
+  deviceId: string;
+  stepUp: DoomApiCallerStepUp;
+};
+/** Reads the proxy-authenticated caller identity, rejecting partial or contradictory stamps. */
+export declare function doomApiCallerFrom(headers: Headers): DoomApiCaller | undefined;
+/**
+ * A browser-reachable OAuth redirect the host serves on its own listener.
+ *
+ * A package brokering third-party OAuth cannot use a loopback redirect when the
+ * operator's browser is on another machine: `127.0.0.1` resolves to whichever
+ * machine the browser runs on. The host owns a listener that is reachable from
+ * wherever the cockpit is being used, so it lends that instead of the package
+ * opening a port of its own.
+ */
+export interface DoomOAuthRedirect {
+  /** Absolute URL to register as the redirect target, already origin-correct. */
+  readonly redirectUri: string;
+  /**
+   * Accept redirects carrying this state. Must complete before the
+   * authorization URL is surfaced, or the redirect races its own reservation.
+   */
+  reserve(state: string, timeoutMs?: number): Promise<void>;
+  /** Resolves once the redirect carrying this state arrives. */
+  wait(state: string, timeoutMs?: number): Promise<{
+    code: string;
+    state: string;
+  }>;
+  /** Drops a reservation whose flow ended without a redirect. */
+  cancel(state: string): void;
+}
+/** An exact, host-owned receipt address. Provider IDs are not event cursor positions. */
+export interface DoomRequestReceiptKey {
+  namespace: string;
+  activationId: string;
+  requestId: string;
+}
+export interface DoomRequestReceipt extends DoomRequestReceiptKey {
+  fingerprint: string;
+  destination: string;
+  transactionId: string;
+  outcome: 'reserved' | 'admitted' | 'rejected' | 'uncertain';
+}
+export interface DoomRequestReceiptReservation extends DoomRequestReceiptKey {
+  /** Lowercase SHA-256 of the authoritative request text, never the full transcript. */
+  fingerprint: string;
+  destination: string;
+  transactionId: string;
+}
+export type DoomRequestReceiptReserveResult = {
+  kind: 'reserved';
+  token: string;
+} | {
+  kind: 'existing';
+  receipt: DoomRequestReceipt;
+} | {
+  kind: 'conflict';
+  receipt: DoomRequestReceipt;
+};
+/** A global-only receipt capability. A reservation is not an execution receipt. */
+export interface DoomRequestReceipts {
+  reserve(request: DoomRequestReceiptReservation): Promise<DoomRequestReceiptReserveResult>;
+  lookup(key: DoomRequestReceiptKey): Promise<DoomRequestReceipt | undefined>;
+  finish(request: DoomRequestReceiptKey & {
+    token: string;
+    outcome: 'admitted' | 'rejected' | 'uncertain';
+  }): Promise<DoomRequestReceipt>;
+}
+/** Permit returned for expensive local work. Calling it releases the slot. */
+export interface DoomHostExecutionPermit {
+  (): void;
+  attachProcess?(pid: number): Promise<void>;
+}
+/** Host-wide admission for expensive local work. Release only after the owned process exits. */
+export interface DoomHostExecutionBudget {
+  acquire(signal?: AbortSignal): Promise<DoomHostExecutionPermit>;
+  getSnapshot(): Readonly<{
+    running: number;
+    queued: number;
+    limit: number;
+  }>;
+}
+/** Synchronous host-owned exclusion across media APIs mounted at different scopes. */
+export interface DoomHostMediaArbitration {
+  register(busy: () => boolean): () => void;
+  available(busy: () => boolean): boolean;
+}
+/** One host's paired agent registrations, shared across its global and session mounts. */
+export interface DoomPeerAgentRegistry {
+  register(sessionId: string, agent: {
+    fetch(request: Request): Promise<Response>;
+  }, hubToken: string): () => void;
+  get(sessionId: string): {
+    fetch(request: Request): Promise<Response>;
+    hubToken: string;
+  } | undefined;
+}
+/** What the host tells an API about itself when it starts. */
+export interface DoomApiContext {
+  scope: DoomApiScope;
+  /** Stable, opaque workspace id, shared by every session and member checkout of the workspace. */
+  workspaceId?: string;
+  /**
+   * The admitted workspace root for a workspace mount. For a session mount it is the checkout
+   * the session runs in; read sessionContext for both roots. Absent from global mounts.
+   */
+  workspaceRoot?: string;
+  /** The session's baseline context; present on session mounts whose host knows its workspace. */
+  sessionContext?: DoomSessionContext;
+  /** Explicit host home, never selected by a remote request. */
+  homeDirectory?: string;
+  /** The session this host serves; absent for a hub-scoped API. */
+  sessionId?: string;
+  /** The session's working directory; absent for a hub-scoped API. */
+  cwd?: string;
+  /** Session environment admitted by the server, never supplied by remote clients. */
+  environment?: Readonly<Record<string, string | undefined>>;
+  /** Shared only with child processes in this session, never with remote API clients. */
+  internalToken?: string;
+  /** Shared only with the cockpit hub for privileged cross-session coordination. */
+  hubToken?: string;
+  /**
+   * Resolves a hub-issued opaque repository id to an admitted canonical root.
+   * Hub APIs must never accept a browser-supplied filesystem path instead.
+   */
+  resolveRepository?(repositoryId: string): string | undefined;
+  /** Reads the admitted repository's sync projection without exposing its state path. */
+  readRepositorySync?(repositoryId: string): DoomRepositorySyncView | undefined;
+  /** Admitted workspaces available to this mount. */
+  repositories?(): readonly {
+    id: string;
+    name: string;
+    path: string;
+    active: boolean;
+  }[];
+  /** Publish a successful config write to the owning mount's refresh lifecycle. */
+  configurationChanged?(): void;
+  /**
+   * Borrows the hub's OAuth redirect surface. Undefined when the hub cannot
+   * currently serve one, in which case the package keeps its own behaviour.
+   */
+  oauthRedirect?(): DoomOAuthRedirect | undefined;
+  /** Canonical in-process lifecycle for sessions created by this host. */
+  sessionService?: DoomHubSessionService;
+  /** Host-bound, authenticated inter-session event endpoint for this session. */
+  sessionCommunication?: DoomSessionCommunicationEndpoint;
+  /** Same-process events shared by session APIs and hub channels. */
+  directEvents?: DoomDirectEventBus;
+  /** Trusted in-process dispatch to an explicitly selected mounted API. No browser authentication is performed here. */
+  requestApi?(mount: DoomApiMount, basePath: string, request: Request): Promise<Response>;
+  /** Present only on a session mounted by an authenticated Desktop host. */
+  computerUse?: DoomComputerUseSessionAccess;
+  /** Deliver a typed method to a channel on this exact hub mount, retaining the caller's connection identity. */
+  receiveChannel?(sessionId: string, frameType: string, payload: unknown, connectionId: string): boolean;
+  /** Host-owned replay evidence, supplied only on the global mount. Never exposed to browsers or agents. */
+  requestReceipts?: DoomRequestReceipts;
+  /** One host's exclusive media activity, shared across global and session scopes. */
+  mediaArbitration?: DoomHostMediaArbitration;
+  /** One host-wide heavy-job budget, not a separate budget for every session. */
+  executionBudget?: DoomHostExecutionBudget;
+  /** Paired agents belonging to this host only. */
+  peerAgents?: DoomPeerAgentRegistry;
+  /** Machine-owned Remote Control service, mounted only by the global core facet. */
+  remoteControl?: {
+    fetch(request: Request): Promise<Response>;
+  };
+  onNotice(message: string): void;
+}
+/**
+ * One running surface. The host strips the mount prefix before calling, so
+ * routes are declared relative ('/runners/:id/log') and a package never
+ * repeats where it was mounted.
+ */
+export interface DoomApiHandler {
+  fetch(request: Request): Response | Promise<Response>;
+  close(): void;
+}
+export interface DoomApi {
+  /** Segment under /api/plugins/; globally unique across loaded packages. */
+  basePath: string;
+  start(context: DoomApiContext): DoomApiHandler;
+}
+//#endregion
+//# sourceMappingURL=packageApi.d.mts.map

package/dist/src/schemas/packageApi.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"packageApi.d.mts","names":[],"sources":["../../../src/schemas/packageApi.ts"],"mappings":";;;;iBAmBiB;EACf;EACA;EACA,gBAAgB;;;YAIN;qBAEC,0BAA0B;;YAG3B;EACN;;EACA;EAAoB;;EACpB;EAAkB;;;iBAGP;EACf;EACA,OAAO;EACP;EACA;EACA;EACA;EACA;EACA;EACA;;;wBAIc,iBAAiB,OAAO;EAAiB;;;YAQ7C;EACN;;EACA;EAAoB;;EACpB;EAAkB;EAAqB;;;wBAG7B,oBAAoB,mBAAmB;;qBAe1C;;qBAEA;;qBAGA;qBACA;qBACA;qBACA;YAMD;YACA;EACN;EAAmB;;EACnB;EAAoB;EAAkB,QAAQ;;;wBAGpC,kBAAkB,SAAS,UAAU;;;;;;;;;;iBA0BpC;;WAEN;;;;;EAKT,QAAQ,eAAe,qBAAqB;;EAE5C,KAAK,eAAe,qBAAqB;IAAU;IAAc;;;EAEjE,OAAO;;;iBAIQ;EACf;EACA;EACA;;iBAGe,2BAA2B;EAC1C;EACA;EACA;EACA;;iBAGe,sCAAsC;;EAErD;EACA;EACA;;YAGU;EACN;EAAkB;;EAClB;EAAkB,SAAS;;EAC3B;EAAkB,SAAS;;;iBAGhB;EACf,QAAQ,SAAS,gCAAgC,QAAQ;EACzD,OAAO,KAAK,wBAAwB,QAAQ;EAC5C,OACE,SAAS;IAA0B;IAAe;MACjD,QAAQ;;;iBAII;;EAEf,eAAe,cAAc;;;iBAId;EACf,QAAQ,SAAS,cAAc,QAAQ;EACvC,eAAe;IAAW;IAAiB;IAAgB;;;;iBAI5C;EACf,SAAS;EACT,UAAU;;;iBAIK;EACf,SAAS,mBAAmB;IAAS,MAAM,SAAS,UAAU,QAAQ;KAAa;EACnF,IAAI;IAAsB,MAAM,SAAS,UAAU,QAAQ;IAAW;;;;iBAIvD;EACf,OAAO;;EAEP;;;;;EAKA;;EAEA,iBAAiB;;EAEjB;;EAEA;;EAEA;;EAEA,cAAc,SAAS;;EAEvB;;EAEA;;;;;EAKA,mBAAmB;;EAEnB,oBAAoB,uBAAuB;;EAE3C;IAA4B;IAAY;IAAc;IAAc;;;EAEpE;;;;;EAKA,kBAAkB;;EAElB,iBAAiB;;EAEjB,uBAAuB;;EAEvB,eAAe;;EAEf,YAAY,OAAO,cAAc,kBAAkB,SAAS,UAAU,QAAQ;;EAE9E,cAAc;;EAEd,gBAAgB,mBAAmB,mBAAmB,kBAAkB;;EAExE,kBAAkB;;EAElB,mBAAmB;;EAEnB,kBAAkB;;EAElB,aAAa;;EAEb;IAAkB,MAAM,SAAS,UAAU,QAAQ;;EACnD,SAAS;;;;;;;iBAQM;EACf,MAAM,SAAS,UAAU,WAAW,QAAQ;EAC5C;;iBAGe;;EAEf;EACA,MAAM,SAAS,iBAAiB"}

package/dist/src/schemas/packageApi.mjs

@@ -0,0 +1,64 @@
+//#region src/schemas/packageApi.ts
+const DOOM_API_SCOPES = [
+	"global",
+	"workspace",
+	"session"
+];
+/** Canonical public prefix. Scope selection never falls through to a parent. */
+function doomApiMountPath(mount) {
+	if (mount.scope === "global") return "/api/plugins";
+	if (mount.scope === "workspace") return `/api/workspaces/${encodeURIComponent(mount.workspaceId)}/plugins`;
+	if (!mount.workspaceId) throw new Error("A session API path requires its workspace identity.");
+	return `/api/workspaces/${encodeURIComponent(mount.workspaceId)}/sessions/${encodeURIComponent(mount.sessionId)}/plugins`;
+}
+/** Only canonical resource paths may select a protocol listener. */
+function parseDoomSocketPath(pathname) {
+	if (pathname === "/api/ws") return { scope: "global" };
+	const match = /^\/api\/workspaces\/([^/]+)(?:\/sessions\/([^/]+))?\/ws$/u.exec(pathname);
+	if (!match) return void 0;
+	try {
+		const workspaceId = decodeURIComponent(match[1]);
+		return match[2] === void 0 ? {
+			scope: "workspace",
+			workspaceId
+		} : {
+			scope: "session",
+			workspaceId,
+			sessionId: decodeURIComponent(match[2])
+		};
+	} catch {
+		return;
+	}
+}
+/** The segment an API is mounted under, below this prefix. */
+const DOOM_API_ROUTE_PREFIX = "/api/plugins";
+/** Selects the hub API bundle that owns the named cockpit session. */
+const DOOM_HUB_API_SESSION_QUERY_PARAM = "hubSession";
+/** Trusted caller headers written only by the cockpit-to-session proxy. */
+const DOOM_API_CALLER_LOCALITY_HEADER = "x-doompi-api-caller-locality";
+const DOOM_API_CALLER_DEVICE_ID_HEADER = "x-doompi-api-caller-device-id";
+const DOOM_API_CALLER_STEP_UP_HEADER = "x-doompi-api-caller-step-up";
+const DOOM_API_CALLER_HEADERS = [
+	DOOM_API_CALLER_LOCALITY_HEADER,
+	DOOM_API_CALLER_DEVICE_ID_HEADER,
+	DOOM_API_CALLER_STEP_UP_HEADER
+];
+/** Reads the proxy-authenticated caller identity, rejecting partial or contradictory stamps. */
+function doomApiCallerFrom(headers) {
+	const locality = headers.get(DOOM_API_CALLER_LOCALITY_HEADER);
+	const deviceId = headers.get(DOOM_API_CALLER_DEVICE_ID_HEADER);
+	const stepUp = headers.get(DOOM_API_CALLER_STEP_UP_HEADER);
+	if (locality === "local") return deviceId === null && stepUp === "not-required" ? {
+		locality,
+		stepUp
+	} : void 0;
+	if (locality === "remote" && deviceId !== null && deviceId !== "" && (stepUp === "not-required" || stepUp === "verified" || stepUp === "unavailable")) return {
+		locality,
+		deviceId,
+		stepUp
+	};
+}
+//#endregion
+export { DOOM_API_CALLER_DEVICE_ID_HEADER, DOOM_API_CALLER_HEADERS, DOOM_API_CALLER_LOCALITY_HEADER, DOOM_API_CALLER_STEP_UP_HEADER, DOOM_API_ROUTE_PREFIX, DOOM_API_SCOPES, DOOM_HUB_API_SESSION_QUERY_PARAM, doomApiCallerFrom, doomApiMountPath, parseDoomSocketPath };
+
+//# sourceMappingURL=packageApi.mjs.map

package/dist/src/schemas/packageApi.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"packageApi.mjs","names":[],"sources":["../../../src/schemas/packageApi.ts"],"sourcesContent":["/**\n * The HTTP surface a package offers its host.\n *\n * A server facet registers one with its host. The host mounts it under the API\n * route prefix, and the package writes routes relative to that mount.\n *\n * The handler is a plain fetch callback so no host and no package is committed\n * to one HTTP framework; a Hono app satisfies it through `app.fetch`.\n */\n\nimport type {\n  DoomComputerUseSessionAccess,\n  DoomDirectEventBus,\n  DoomHubSessionService,\n  DoomSessionCommunicationEndpoint,\n  DoomSessionContext,\n} from './hubChannel';\nimport type { DoomMcpProjection } from './mcpProjection';\n/** The host-owned sync view a repository-scoped package API may inspect. */\nexport interface DoomRepositorySyncView {\n  fresh: boolean;\n  reasons: string[];\n  mcpProjection?: DoomMcpProjection;\n}\n\n/** Where an API runs: inside one session's server, or in the machine-wide hub. */\nexport type DoomApiScope = 'global' | 'workspace' | 'session';\n\nexport const DOOM_API_SCOPES: readonly DoomApiScope[] = ['global', 'workspace', 'session'];\n\n/** Identity of an independently mounted plugin host. */\nexport type DoomApiMount =\n  | { scope: 'global' }\n  | { scope: 'workspace'; workspaceId: string }\n  | { scope: 'session'; sessionId: string };\n\n/** Immutable browser contribution generation paired with a server mount. */\nexport interface DoomWebComposition {\n  id: string;\n  scope: DoomApiScope;\n  revision: number;\n  manifestUrl: string;\n  rawAssetBaseUrl: string;\n  verifiedAssetBaseUrl: string;\n  entryPath: string;\n  stylePaths: string[];\n  channels: string[];\n}\n\n/** Canonical public prefix. Scope selection never falls through to a parent. */\nexport function doomApiMountPath(mount: DoomApiMount & { workspaceId?: string }): string {\n  if (mount.scope === 'global') return '/api/plugins';\n  if (mount.scope === 'workspace') return `/api/workspaces/${encodeURIComponent(mount.workspaceId)}/plugins`;\n  if (!mount.workspaceId) throw new Error('A session API path requires its workspace identity.');\n  return `/api/workspaces/${encodeURIComponent(mount.workspaceId)}/sessions/${encodeURIComponent(mount.sessionId)}/plugins`;\n}\n\n/** Scope addressed by a public WebSocket upgrade. */\nexport type DoomSocketMount =\n  | { scope: 'global' }\n  | { scope: 'workspace'; workspaceId: string }\n  | { scope: 'session'; workspaceId: string; sessionId: string };\n\n/** Only canonical resource paths may select a protocol listener. */\nexport function parseDoomSocketPath(pathname: string): DoomSocketMount | undefined {\n  if (pathname === '/api/ws') return { scope: 'global' };\n  const match = /^\\/api\\/workspaces\\/([^/]+)(?:\\/sessions\\/([^/]+))?\\/ws$/u.exec(pathname);\n  if (!match) return undefined;\n  try {\n    const workspaceId = decodeURIComponent(match[1]);\n    return match[2] === undefined\n      ? { scope: 'workspace', workspaceId }\n      : { scope: 'session', workspaceId, sessionId: decodeURIComponent(match[2]) };\n  } catch {\n    return undefined;\n  }\n}\n\n/** The segment an API is mounted under, below this prefix. */\nexport const DOOM_API_ROUTE_PREFIX = '/api/plugins';\n/** Selects the hub API bundle that owns the named cockpit session. */\nexport const DOOM_HUB_API_SESSION_QUERY_PARAM = 'hubSession';\n\n/** Trusted caller headers written only by the cockpit-to-session proxy. */\nexport const DOOM_API_CALLER_LOCALITY_HEADER = 'x-doompi-api-caller-locality';\nexport const DOOM_API_CALLER_DEVICE_ID_HEADER = 'x-doompi-api-caller-device-id';\nexport const DOOM_API_CALLER_STEP_UP_HEADER = 'x-doompi-api-caller-step-up';\nexport const DOOM_API_CALLER_HEADERS = [\n  DOOM_API_CALLER_LOCALITY_HEADER,\n  DOOM_API_CALLER_DEVICE_ID_HEADER,\n  DOOM_API_CALLER_STEP_UP_HEADER,\n] as const;\n\nexport type DoomApiCallerStepUp = 'not-required' | 'verified' | 'unavailable';\nexport type DoomApiCaller =\n  | { locality: 'local'; stepUp: 'not-required' }\n  | { locality: 'remote'; deviceId: string; stepUp: DoomApiCallerStepUp };\n\n/** Reads the proxy-authenticated caller identity, rejecting partial or contradictory stamps. */\nexport function doomApiCallerFrom(headers: Headers): DoomApiCaller | undefined {\n  const locality = headers.get(DOOM_API_CALLER_LOCALITY_HEADER);\n  const deviceId = headers.get(DOOM_API_CALLER_DEVICE_ID_HEADER);\n  const stepUp = headers.get(DOOM_API_CALLER_STEP_UP_HEADER);\n  if (locality === 'local') {\n    return deviceId === null && stepUp === 'not-required' ? { locality, stepUp } : undefined;\n  }\n  if (\n    locality === 'remote' &&\n    deviceId !== null &&\n    deviceId !== '' &&\n    (stepUp === 'not-required' || stepUp === 'verified' || stepUp === 'unavailable')\n  ) {\n    return { locality, deviceId, stepUp };\n  }\n  return undefined;\n}\n/**\n * A browser-reachable OAuth redirect the host serves on its own listener.\n *\n * A package brokering third-party OAuth cannot use a loopback redirect when the\n * operator's browser is on another machine: `127.0.0.1` resolves to whichever\n * machine the browser runs on. The host owns a listener that is reachable from\n * wherever the cockpit is being used, so it lends that instead of the package\n * opening a port of its own.\n */\nexport interface DoomOAuthRedirect {\n  /** Absolute URL to register as the redirect target, already origin-correct. */\n  readonly redirectUri: string;\n  /**\n   * Accept redirects carrying this state. Must complete before the\n   * authorization URL is surfaced, or the redirect races its own reservation.\n   */\n  reserve(state: string, timeoutMs?: number): Promise<void>;\n  /** Resolves once the redirect carrying this state arrives. */\n  wait(state: string, timeoutMs?: number): Promise<{ code: string; state: string }>;\n  /** Drops a reservation whose flow ended without a redirect. */\n  cancel(state: string): void;\n}\n\n/** An exact, host-owned receipt address. Provider IDs are not event cursor positions. */\nexport interface DoomRequestReceiptKey {\n  namespace: string;\n  activationId: string;\n  requestId: string;\n}\n\nexport interface DoomRequestReceipt extends DoomRequestReceiptKey {\n  fingerprint: string;\n  destination: string;\n  transactionId: string;\n  outcome: 'reserved' | 'admitted' | 'rejected' | 'uncertain';\n}\n\nexport interface DoomRequestReceiptReservation extends DoomRequestReceiptKey {\n  /** Lowercase SHA-256 of the authoritative request text, never the full transcript. */\n  fingerprint: string;\n  destination: string;\n  transactionId: string;\n}\n\nexport type DoomRequestReceiptReserveResult =\n  | { kind: 'reserved'; token: string }\n  | { kind: 'existing'; receipt: DoomRequestReceipt }\n  | { kind: 'conflict'; receipt: DoomRequestReceipt };\n\n/** A global-only receipt capability. A reservation is not an execution receipt. */\nexport interface DoomRequestReceipts {\n  reserve(request: DoomRequestReceiptReservation): Promise<DoomRequestReceiptReserveResult>;\n  lookup(key: DoomRequestReceiptKey): Promise<DoomRequestReceipt | undefined>;\n  finish(\n    request: DoomRequestReceiptKey & { token: string; outcome: 'admitted' | 'rejected' | 'uncertain' },\n  ): Promise<DoomRequestReceipt>;\n}\n\n/** Permit returned for expensive local work. Calling it releases the slot. */\nexport interface DoomHostExecutionPermit {\n  (): void;\n  attachProcess?(pid: number): Promise<void>;\n}\n\n/** Host-wide admission for expensive local work. Release only after the owned process exits. */\nexport interface DoomHostExecutionBudget {\n  acquire(signal?: AbortSignal): Promise<DoomHostExecutionPermit>;\n  getSnapshot(): Readonly<{ running: number; queued: number; limit: number }>;\n}\n\n/** Synchronous host-owned exclusion across media APIs mounted at different scopes. */\nexport interface DoomHostMediaArbitration {\n  register(busy: () => boolean): () => void;\n  available(busy: () => boolean): boolean;\n}\n\n/** One host's paired agent registrations, shared across its global and session mounts. */\nexport interface DoomPeerAgentRegistry {\n  register(sessionId: string, agent: { fetch(request: Request): Promise<Response> }, hubToken: string): () => void;\n  get(sessionId: string): { fetch(request: Request): Promise<Response>; hubToken: string } | undefined;\n}\n\n/** What the host tells an API about itself when it starts. */\nexport interface DoomApiContext {\n  scope: DoomApiScope;\n  /** Stable, opaque workspace id, shared by every session and member checkout of the workspace. */\n  workspaceId?: string;\n  /**\n   * The admitted workspace root for a workspace mount. For a session mount it is the checkout\n   * the session runs in; read sessionContext for both roots. Absent from global mounts.\n   */\n  workspaceRoot?: string;\n  /** The session's baseline context; present on session mounts whose host knows its workspace. */\n  sessionContext?: DoomSessionContext;\n  /** Explicit host home, never selected by a remote request. */\n  homeDirectory?: string;\n  /** The session this host serves; absent for a hub-scoped API. */\n  sessionId?: string;\n  /** The session's working directory; absent for a hub-scoped API. */\n  cwd?: string;\n  /** Session environment admitted by the server, never supplied by remote clients. */\n  environment?: Readonly<Record<string, string | undefined>>;\n  /** Shared only with child processes in this session, never with remote API clients. */\n  internalToken?: string;\n  /** Shared only with the cockpit hub for privileged cross-session coordination. */\n  hubToken?: string;\n  /**\n   * Resolves a hub-issued opaque repository id to an admitted canonical root.\n   * Hub APIs must never accept a browser-supplied filesystem path instead.\n   */\n  resolveRepository?(repositoryId: string): string | undefined;\n  /** Reads the admitted repository's sync projection without exposing its state path. */\n  readRepositorySync?(repositoryId: string): DoomRepositorySyncView | undefined;\n  /** Admitted workspaces available to this mount. */\n  repositories?(): readonly { id: string; name: string; path: string; active: boolean }[];\n  /** Publish a successful config write to the owning mount's refresh lifecycle. */\n  configurationChanged?(): void;\n  /**\n   * Borrows the hub's OAuth redirect surface. Undefined when the hub cannot\n   * currently serve one, in which case the package keeps its own behaviour.\n   */\n  oauthRedirect?(): DoomOAuthRedirect | undefined;\n  /** Canonical in-process lifecycle for sessions created by this host. */\n  sessionService?: DoomHubSessionService;\n  /** Host-bound, authenticated inter-session event endpoint for this session. */\n  sessionCommunication?: DoomSessionCommunicationEndpoint;\n  /** Same-process events shared by session APIs and hub channels. */\n  directEvents?: DoomDirectEventBus;\n  /** Trusted in-process dispatch to an explicitly selected mounted API. No browser authentication is performed here. */\n  requestApi?(mount: DoomApiMount, basePath: string, request: Request): Promise<Response>;\n  /** Present only on a session mounted by an authenticated Desktop host. */\n  computerUse?: DoomComputerUseSessionAccess;\n  /** Deliver a typed method to a channel on this exact hub mount, retaining the caller's connection identity. */\n  receiveChannel?(sessionId: string, frameType: string, payload: unknown, connectionId: string): boolean;\n  /** Host-owned replay evidence, supplied only on the global mount. Never exposed to browsers or agents. */\n  requestReceipts?: DoomRequestReceipts;\n  /** One host's exclusive media activity, shared across global and session scopes. */\n  mediaArbitration?: DoomHostMediaArbitration;\n  /** One host-wide heavy-job budget, not a separate budget for every session. */\n  executionBudget?: DoomHostExecutionBudget;\n  /** Paired agents belonging to this host only. */\n  peerAgents?: DoomPeerAgentRegistry;\n  /** Machine-owned Remote Control service, mounted only by the global core facet. */\n  remoteControl?: { fetch(request: Request): Promise<Response> };\n  onNotice(message: string): void;\n}\n\n/**\n * One running surface. The host strips the mount prefix before calling, so\n * routes are declared relative ('/runners/:id/log') and a package never\n * repeats where it was mounted.\n */\nexport interface DoomApiHandler {\n  fetch(request: Request): Response | Promise<Response>;\n  close(): void;\n}\n\nexport interface DoomApi {\n  /** Segment under /api/plugins/; globally unique across loaded packages. */\n  basePath: string;\n  start(context: DoomApiContext): DoomApiHandler;\n}\n"],"mappings":";AA4BA,MAAa,kBAA2C;CAAC;CAAU;CAAa;AAAS;;AAsBzF,SAAgB,iBAAiB,OAAwD;CACvF,IAAI,MAAM,UAAU,UAAU,OAAO;CACrC,IAAI,MAAM,UAAU,aAAa,OAAO,mBAAmB,mBAAmB,MAAM,WAAW,EAAE;CACjG,IAAI,CAAC,MAAM,aAAa,MAAM,IAAI,MAAM,qDAAqD;CAC7F,OAAO,mBAAmB,mBAAmB,MAAM,WAAW,EAAE,YAAY,mBAAmB,MAAM,SAAS,EAAE;AAClH;;AASA,SAAgB,oBAAoB,UAA+C;CACjF,IAAI,aAAa,WAAW,OAAO,EAAE,OAAO,SAAS;CACrD,MAAM,QAAQ,4DAA4D,KAAK,QAAQ;CACvF,IAAI,CAAC,OAAO,OAAO,KAAA;CACnB,IAAI;EACF,MAAM,cAAc,mBAAmB,MAAM,EAAE;EAC/C,OAAO,MAAM,OAAO,KAAA,IAChB;GAAE,OAAO;GAAa;EAAY,IAClC;GAAE,OAAO;GAAW;GAAa,WAAW,mBAAmB,MAAM,EAAE;EAAE;CAC/E,QAAQ;EACN;CACF;AACF;;AAGA,MAAa,wBAAwB;;AAErC,MAAa,mCAAmC;;AAGhD,MAAa,kCAAkC;AAC/C,MAAa,mCAAmC;AAChD,MAAa,iCAAiC;AAC9C,MAAa,0BAA0B;CACrC;CACA;CACA;AACF;;AAQA,SAAgB,kBAAkB,SAA6C;CAC7E,MAAM,WAAW,QAAQ,IAAI,+BAA+B;CAC5D,MAAM,WAAW,QAAQ,IAAI,gCAAgC;CAC7D,MAAM,SAAS,QAAQ,IAAI,8BAA8B;CACzD,IAAI,aAAa,SACf,OAAO,aAAa,QAAQ,WAAW,iBAAiB;EAAE;EAAU;CAAO,IAAI,KAAA;CAEjF,IACE,aAAa,YACb,aAAa,QACb,aAAa,OACZ,WAAW,kBAAkB,WAAW,cAAc,WAAW,gBAElE,OAAO;EAAE;EAAU;EAAU;CAAO;AAGxC"}

package/dist/src/schemas/piTool.cjs

@@ -0,0 +1,26 @@
+//#region src/schemas/piTool.ts
+function definePiTool(definition, options = {}) {
+	return {
+		kind: "pi-tool",
+		name: definition.name,
+		...options.overrides === true ? { overrides: true } : {},
+		register(pi, executionSignal) {
+			if (!executionSignal) {
+				pi.registerTool(definition);
+				return;
+			}
+			pi.registerTool({
+				...definition,
+				async execute(toolCallId, input, signal, update, context) {
+					const current = executionSignal();
+					current.throwIfAborted();
+					return definition.execute(toolCallId, input, signal ? AbortSignal.any([signal, current]) : current, update, context);
+				}
+			});
+		}
+	};
+}
+//#endregion
+exports.definePiTool = definePiTool;
+
+//# sourceMappingURL=piTool.cjs.map

package/dist/src/schemas/piTool.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"piTool.cjs","names":[],"sources":["../../../src/schemas/piTool.ts"],"sourcesContent":["import type { ExtensionAPI, ToolDefinition } from '@earendil-works/pi-coding-agent';\nimport type { TSchema } from 'typebox';\n\n/** A schema-checked native tool whose concrete input/details types stay inside its registration closure. */\nexport interface PiToolDeclaration {\n  readonly kind: 'pi-tool';\n  readonly name: string;\n  /**\n   * Claims a name another extension already registers, rather than adding one.\n   *\n   * Pi ships its own grep, read and edit, so a package that improves one of\n   * them is replacing a name rather than contributing a new one. Only one\n   * package may win a given name, which is why this is a claim arbitrated by\n   * the tool-override service and not simply a second registration.\n   */\n  readonly overrides?: boolean;\n  register(pi: Pick<ExtensionAPI, 'registerTool'>, executionSignal?: () => AbortSignal): void;\n}\n\nexport interface PiToolOptions {\n  /** Replace a name another extension registers instead of adding a new one. */\n  readonly overrides?: boolean;\n}\n\nexport function definePiTool<TParameters extends TSchema, TDetails, TState>(\n  definition: ToolDefinition<TParameters, TDetails, TState>,\n  options: PiToolOptions = {},\n): PiToolDeclaration {\n  return {\n    kind: 'pi-tool',\n    name: definition.name,\n    ...(options.overrides === true ? { overrides: true } : {}),\n    register(pi, executionSignal) {\n      if (!executionSignal) {\n        pi.registerTool(definition);\n        return;\n      }\n      pi.registerTool({\n        ...definition,\n        async execute(toolCallId, input, signal, update, context) {\n          const current = executionSignal();\n          current.throwIfAborted();\n          return definition.execute(\n            toolCallId,\n            input,\n            signal ? AbortSignal.any([signal, current]) : current,\n            update,\n            context,\n          );\n        },\n      });\n    },\n  };\n}\n"],"mappings":";AAwBA,SAAgB,aACd,YACA,UAAyB,CAAC,GACP;CACnB,OAAO;EACL,MAAM;EACN,MAAM,WAAW;EACjB,GAAI,QAAQ,cAAc,OAAO,EAAE,WAAW,KAAK,IAAI,CAAC;EACxD,SAAS,IAAI,iBAAiB;GAC5B,IAAI,CAAC,iBAAiB;IACpB,GAAG,aAAa,UAAU;IAC1B;GACF;GACA,GAAG,aAAa;IACd,GAAG;IACH,MAAM,QAAQ,YAAY,OAAO,QAAQ,QAAQ,SAAS;KACxD,MAAM,UAAU,gBAAgB;KAChC,QAAQ,eAAe;KACvB,OAAO,WAAW,QAChB,YACA,OACA,SAAS,YAAY,IAAI,CAAC,QAAQ,OAAO,CAAC,IAAI,SAC9C,QACA,OACF;IACF;GACF,CAAC;EACH;CACF;AACF"}

package/dist/src/schemas/piTool.d.mts

@@ -0,0 +1,25 @@
+import { TSchema } from "typebox";
+import { ExtensionAPI, ToolDefinition } from "@earendil-works/pi-coding-agent";
+//#region src/schemas/piTool.d.ts
+/** A schema-checked native tool whose concrete input/details types stay inside its registration closure. */
+export interface PiToolDeclaration {
+  readonly kind: 'pi-tool';
+  readonly name: string;
+  /**
+   * Claims a name another extension already registers, rather than adding one.
+   *
+   * Pi ships its own grep, read and edit, so a package that improves one of
+   * them is replacing a name rather than contributing a new one. Only one
+   * package may win a given name, which is why this is a claim arbitrated by
+   * the tool-override service and not simply a second registration.
+   */
+  readonly overrides?: boolean;
+  register(pi: Pick<ExtensionAPI, 'registerTool'>, executionSignal?: () => AbortSignal): void;
+}
+export interface PiToolOptions {
+  /** Replace a name another extension registers instead of adding a new one. */
+  readonly overrides?: boolean;
+}
+export declare function definePiTool<TParameters extends TSchema, TDetails, TState>(definition: ToolDefinition<TParameters, TDetails, TState>, options?: PiToolOptions): PiToolDeclaration;
+//#endregion
+//# sourceMappingURL=piTool.d.mts.map