@pstdio/pocketcoder-sdk 0.5.0 → 0.6.1

package/dist/index.js

@@ -1,6 +1,221 @@
 import { z } from "zod";
 import { isIP } from "node:net";
-//#region ../contracts/src/pagination.ts
+//#region ../contracts/src/attachments/attachment.ts
+const ATTACHMENT_MAX_FILE_BYTES = 26214400;
+const ATTACHMENT_CHUNK_BYTES = 524288;
+const AttachmentMediaTypeSchema = z.string().regex(/^[\w.+-]+\/[\w.+-]+$/).max(255);
+const AttachmentDescriptorSchema = z.object({
+	id: z.uuid(),
+	name: z.string().min(1).max(255),
+	path: z.string().min(1),
+	media_type: AttachmentMediaTypeSchema,
+	size_bytes: z.number().int().min(0).max(ATTACHMENT_MAX_FILE_BYTES),
+	sha256: z.string().regex(/^[0-9a-f]{64}$/)
+});
+z.looseObject({
+	type: z.literal("user"),
+	content: z.string(),
+	attachment_ids: z.array(z.uuid()).min(1).max(10).refine((ids) => new Set(ids).size === ids.length, "attachment_ids must be unique").optional()
+});
+const MANIFEST_OPEN = "<pocketcoder-attachments>";
+const MANIFEST_CLOSE = "</pocketcoder-attachments>";
+function splitAttachmentManifest(content) {
+	const open = content.lastIndexOf(MANIFEST_OPEN);
+	if (open < 0 || !content.trimEnd().endsWith(MANIFEST_CLOSE)) return {
+		text: content,
+		attachments: null
+	};
+	const close = content.lastIndexOf(MANIFEST_CLOSE);
+	const parsed = z.array(AttachmentDescriptorSchema).safeParse(safeJson(content.slice(open + 25, close)));
+	if (!parsed.success) return {
+		text: content,
+		attachments: null
+	};
+	return {
+		text: content.slice(0, open).trimEnd(),
+		attachments: parsed.data
+	};
+}
+function safeJson(value) {
+	try {
+		return JSON.parse(value);
+	} catch {
+		return;
+	}
+}
+const AttachmentStartPayload = z.object({
+	operation_id: z.uuid(),
+	attachment_id: z.uuid(),
+	name: z.string().min(1).max(255),
+	media_type: AttachmentMediaTypeSchema,
+	size_bytes: z.number().int().min(0).max(ATTACHMENT_MAX_FILE_BYTES)
+});
+const AttachmentChunkPayload = z.object({
+	operation_id: z.uuid(),
+	seq: z.number().int().nonnegative(),
+	content_b64: z.string().max(Math.ceil(ATTACHMENT_CHUNK_BYTES / 3) * 4 + 4)
+});
+const AttachmentFinishPayload = z.object({ operation_id: z.uuid() });
+const AttachmentAbortPayload = z.object({
+	operation_id: z.uuid(),
+	reason: z.string().max(512)
+});
+const AttachmentResolvePayload = z.object({
+	operation_id: z.uuid(),
+	attachment_ids: z.array(z.uuid()).min(1).max(10)
+});
+const AttachmentAckPayload = z.object({
+	operation_id: z.uuid(),
+	seq: z.number().int().nonnegative(),
+	received_bytes: z.number().int().nonnegative()
+});
+const AttachmentResultPayload = z.object({
+	operation_id: z.uuid(),
+	status: z.enum([
+		"created",
+		"existing",
+		"conflict",
+		"failed"
+	]),
+	descriptor: AttachmentDescriptorSchema.optional(),
+	failure_code: z.enum([
+		"invalid",
+		"too_large",
+		"sequence",
+		"io",
+		"interrupted"
+	]).optional(),
+	detail: z.string().max(512).optional()
+});
+const AttachmentResolvedPayload = z.object({
+	operation_id: z.uuid(),
+	descriptors: z.array(AttachmentDescriptorSchema).optional(),
+	missing_id: z.uuid().optional()
+});
+//#endregion
+//#region ../contracts/src/common/scopes.ts
+const SCOPES = [
+	"templates:read",
+	"workspaces:create",
+	"workspaces:read",
+	"workspaces:cancel",
+	"workspaces:purge",
+	"workspaces:recover",
+	"keys:read",
+	"keys:write",
+	"workspaces:preserve",
+	"workspaces:restore",
+	"checkpoints:read",
+	"checkpoints:delete",
+	"outputs:read",
+	"conversations:read",
+	"conversations:write",
+	"conversations:delete",
+	"services:relay",
+	"attachments:write",
+	"logs:read",
+	"network:read",
+	"terminal:attach",
+	"terminal:read",
+	"admin"
+];
+z.strictObject({
+	request_id: z.string().min(1).max(128).regex(/^[A-Za-z0-9._:-]+$/),
+	scopes: z.array(z.enum(SCOPES)).min(1).max(SCOPES.length),
+	expires_at: z.iso.datetime()
+});
+const KeyResourceSchema = z.object({
+	id: z.uuid(),
+	principal_id: z.uuid(),
+	scopes: z.array(z.string()),
+	effective_scopes: z.array(z.string()),
+	managed_principal_ids: z.array(z.uuid()),
+	issuance_request_id: z.string().nullable(),
+	created_at: z.iso.datetime(),
+	expires_at: z.iso.datetime().nullable(),
+	revoked_at: z.iso.datetime().nullable(),
+	last_used_at: z.iso.datetime().nullable()
+});
+const KeyIssueResponseSchema = z.object({
+	key: KeyResourceSchema,
+	token: z.string().nullable()
+});
+const KeyListResponseSchema = z.object({
+	items: z.array(KeyResourceSchema),
+	next_cursor: z.uuid().nullable()
+});
+//#endregion
+//#region ../contracts/src/common/duration.ts
+const DURATION_RE = /^(\d+)(ms|s|m|h)$/;
+function isDuration(value) {
+	return DURATION_RE.test(value);
+}
+//#endregion
+//#region ../contracts/src/common/errors.ts
+const ERROR_CODES = {
+	"auth.invalid_key": 401,
+	"auth.missing_scope": 403,
+	"auth.disabled_principal": 403,
+	"principal.not_found": 404,
+	"key.not_found": 404,
+	"validation.invalid": 400,
+	"idempotency.conflict": 409,
+	"capacity.queue_full": 429,
+	"capacity.waiters_full": 429,
+	"template.not_found": 404,
+	"template.version_not_found": 404,
+	"template.not_authorized": 403,
+	"workspace.not_found": 404,
+	"workspace.external_id_conflict": 409,
+	"workspace.not_ready": 409,
+	"workspace.terminal": 410,
+	"workspace.disconnected": 503,
+	"terminal.not_declared": 422,
+	"terminal.session_limit": 409,
+	"terminal.session_not_found": 404,
+	"terminal.session_closed": 409,
+	"terminal.protocol_unsupported": 426,
+	"workspace.persistence_not_enabled": 409,
+	"workspace.preserving": 409,
+	"checkpoint.not_found": 404,
+	"checkpoint.not_ready": 409,
+	"checkpoint.none_ready": 409,
+	"checkpoint.corrupt": 409,
+	"checkpoint.quota_exceeded": 413,
+	"checkpoint.in_use": 409,
+	"restore.template_not_authorized": 403,
+	"restore.image_unavailable": 409,
+	"restore.incompatible": 409,
+	"resume.unsupported": 409,
+	"conversation.expired": 410,
+	"conversation.deleted": 410,
+	"operation.conflict": 409,
+	"source.not_allowed": 422,
+	"source.invalid_revision": 422,
+	"secret.unavailable": 503,
+	"storage.capacity_exhausted": 507,
+	"relay.body_too_large": 413,
+	"relay.route_not_allowed": 422,
+	"relay.streaming_unsupported": 409,
+	"relay.deadline_exceeded": 504,
+	"relay.upstream_error": 502,
+	"attachment.invalid": 400,
+	"attachment.too_large": 413,
+	"attachment.not_found": 404,
+	"attachment.conflict": 409,
+	"attachment.unsupported": 409,
+	"attachment.interrupted": 503,
+	"internal.error": 500
+};
+const errorCodes = Object.keys(ERROR_CODES);
+const ErrorEnvelopeSchema = z.object({ error: z.object({
+	code: z.enum(errorCodes),
+	message: z.string().min(1),
+	request_id: z.string().min(1),
+	details: z.record(z.string(), z.unknown()).optional()
+}) });
+//#endregion
+//#region ../contracts/src/common/pagination.ts
 const CursorSchema = z.string().min(1).max(2048);
 function CursorPageSchema(item) {
 	return z.object({
@@ -15,7 +230,74 @@ function CursorQuerySchema(maxLimit, defaultLimit) {
 	});
 }
 //#endregion
-//#region ../contracts/src/conversation.ts
+//#region ../contracts/src/conversations/facts.ts
+const ConversationFactSchema = z.discriminatedUnion("type", [
+	z.object({ type: z.literal("intermediate") }),
+	z.object({ type: z.literal("final_response") }),
+	z.object({ type: z.literal("tool_only") }),
+	z.object({
+		type: z.literal("activity_started"),
+		activity_id: z.uuid(),
+		kind: z.enum([
+			"tool",
+			"attachment",
+			"workspace",
+			"retrieval"
+		]),
+		label: z.string().min(1).max(160),
+		started_at: z.iso.datetime().nullable()
+	}),
+	z.object({
+		type: z.literal("activity_finished"),
+		activity_id: z.uuid(),
+		ended_at: z.iso.datetime().nullable(),
+		outcome: z.enum([
+			"completed",
+			"failed",
+			"interrupted",
+			"canceled"
+		])
+	}),
+	z.object({
+		type: z.literal("turn_terminal"),
+		outcome: z.enum([
+			"completed",
+			"failed",
+			"interrupted",
+			"canceled",
+			"lost"
+		])
+	})
+]);
+//#endregion
+//#region ../contracts/src/conversations/identity.ts
+const ConversationRequestIdentitySchema = z.object({
+	schema: z.literal("pocketcoder.conversation/v2"),
+	authority: z.enum(["external", "generic"]),
+	conversation_id: z.uuid(),
+	request_id: z.uuid(),
+	turn_id: z.uuid(),
+	request_fingerprint: z.string().regex(/^[0-9a-f]{64}$/)
+});
+const ConversationRequestReceiptSchema = z.object({
+	kind: z.enum(["accepted", "replayed"]),
+	identity: ConversationRequestIdentitySchema,
+	accepted_at: z.iso.datetime()
+});
+const ConversationMessageIdentitySchema = ConversationRequestIdentitySchema.extend({
+	event_id: z.uuid(),
+	message_id: z.string().min(1).max(256),
+	sequence: z.number().int().nonnegative(),
+	revision: z.number().int().positive(),
+	fact: ConversationFactSchema.optional()
+});
+const ConversationProtocolSupportSchema = z.object({
+	schema: z.literal("pocketcoder.conversation/v2"),
+	request_identity_authorities: z.array(z.enum(["external", "generic"])),
+	producer_capabilities: z.null()
+});
+//#endregion
+//#region ../contracts/src/conversations/conversation.ts
 const CONVERSATION_ROLES = [
 	"user",
 	"assistant",
@@ -28,14 +310,21 @@ const ConversationMessageInputSchema = z.object({
 	role: z.enum(CONVERSATION_ROLES),
 	content: z.string().max(262144),
 	occurred_at: z.iso.datetime(),
-	metadata: ConversationMetadataSchema.default({})
+	metadata: ConversationMetadataSchema.default({}),
+	identity: ConversationMessageIdentitySchema.nullable().optional()
+});
+const ConversationMessageResourceSchema = ConversationMessageInputSchema.extend({
+	seq: z.number().int().positive(),
+	identity: ConversationMessageIdentitySchema.nullable().default(null)
 });
-const ConversationMessageResourceSchema = ConversationMessageInputSchema.extend({ seq: z.number().int().positive() });
 CursorQuerySchema(200, 100);
-const ConversationPageSchema = CursorPageSchema(ConversationMessageResourceSchema).extend({ retention: z.object({
-	status: z.literal("retained"),
-	expires_at: z.iso.datetime().nullable()
-}) });
+const ConversationPageSchema = CursorPageSchema(ConversationMessageResourceSchema).extend({
+	protocol: ConversationProtocolSupportSchema.nullable().default(null),
+	retention: z.object({
+		status: z.literal("retained"),
+		expires_at: z.iso.datetime().nullable()
+	})
+});
 const ConversationResumeOutcomeSchema = z.object({
 	status: z.literal("supported"),
 	reason: z.null(),
@@ -43,13 +332,61 @@ const ConversationResumeOutcomeSchema = z.object({
 	checkpoint_id: z.uuid()
 });
 //#endregion
-//#region ../contracts/src/duration.ts
-const DURATION_RE = /^(\d+)(ms|s|m|h)$/;
-function isDuration(value) {
-	return DURATION_RE.test(value);
+//#region ../contracts/src/network/network.ts
+const DOMAIN_LABEL = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
+function isDomain(value) {
+	const domain = value.startsWith("*.") ? value.slice(2) : value;
+	return domain.length <= 253 && !domain.endsWith(".") && isIP(domain) === 0 && domain.split(".").length >= 2 && domain.split(".").every((label) => DOMAIN_LABEL.test(label));
 }
+const NetworkRuleSchema = z.object({
+	domain: z.string().refine(isDomain, "expected a lowercase ASCII domain or leading *. wildcard"),
+	ports: z.array(z.number().int().min(1).max(65535)).min(1).max(32).default([80, 443]),
+	allowPrivate: z.boolean().default(false)
+}).superRefine((rule, ctx) => {
+	if (new Set(rule.ports).size !== rule.ports.length) ctx.addIssue({
+		code: "custom",
+		path: ["ports"],
+		message: "ports must be unique"
+	});
+});
+const UnrestrictedNetworkPolicySchema = z.object({ mode: z.literal("unrestricted") });
+const RestrictedNetworkPolicySchema = z.object({
+	mode: z.literal("restricted"),
+	allow: z.array(NetworkRuleSchema).max(256).default([])
+});
+const NetworkPolicySchema = z.preprocess((value) => value ?? { mode: "unrestricted" }, z.discriminatedUnion("mode", [UnrestrictedNetworkPolicySchema, RestrictedNetworkPolicySchema]));
+const NETWORK_STATES = [
+	"disabled",
+	"starting",
+	"ready",
+	"degraded"
+];
+const NetworkEventInputSchema = z.object({
+	source_seq: z.number().int().positive(),
+	occurred_at: z.iso.datetime(),
+	decision: z.enum(["allow", "deny"]),
+	transport: z.enum(["http", "https"]),
+	host: z.string().min(1).max(253),
+	port: z.number().int().min(1).max(65535),
+	method: z.string().max(32).nullable().default(null),
+	path: z.string().max(2048).refine((path) => !path.includes("?") && !path.includes("#"), "path cannot contain query or fragment").nullable().default(null),
+	matched_rule: z.string().max(512).nullable().default(null),
+	reason: z.string().min(1).max(128)
+});
+z.object({
+	source_session_id: z.uuid(),
+	events: z.array(NetworkEventInputSchema).min(1).max(100)
+});
+const NetworkEventSchema = NetworkEventInputSchema.omit({ source_seq: true }).extend({
+	seq: z.number().int().positive(),
+	workspace_id: z.uuid(),
+	source_session_id: z.uuid(),
+	source_seq: z.number().int().positive()
+});
+CursorQuerySchema(200, 100);
+const NetworkEventPageSchema = CursorPageSchema(NetworkEventSchema);
 //#endregion
-//#region ../contracts/src/persistence.ts
+//#region ../contracts/src/persistence/persistence.ts
 const DurationValueSchema = z.string().refine(isDuration, { message: "expected a duration like 15s, 20m, or 2h" });
 const LAUNCH_MODES = ["create", "restore"];
 const CONVERSATION_RESTORE_CAPABILITIES = [
@@ -117,7 +454,8 @@ const OPERATION_KINDS = [
 	"preserve",
 	"restore",
 	"verify",
-	"delete"
+	"delete",
+	"purge"
 ];
 const OPERATION_STATES = [
 	"pending",
@@ -194,61 +532,7 @@ z.object({
 	file_count: z.number().int().nonnegative()
 });
 //#endregion
-//#region ../contracts/src/network.ts
-const DOMAIN_LABEL = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
-function isDomain(value) {
-	const domain = value.startsWith("*.") ? value.slice(2) : value;
-	return domain.length <= 253 && !domain.endsWith(".") && isIP(domain) === 0 && domain.split(".").length >= 2 && domain.split(".").every((label) => DOMAIN_LABEL.test(label));
-}
-const NetworkRuleSchema = z.object({
-	domain: z.string().refine(isDomain, "expected a lowercase ASCII domain or leading *. wildcard"),
-	ports: z.array(z.number().int().min(1).max(65535)).min(1).max(32).default([80, 443]),
-	allowPrivate: z.boolean().default(false)
-}).superRefine((rule, ctx) => {
-	if (new Set(rule.ports).size !== rule.ports.length) ctx.addIssue({
-		code: "custom",
-		path: ["ports"],
-		message: "ports must be unique"
-	});
-});
-const UnrestrictedNetworkPolicySchema = z.object({ mode: z.literal("unrestricted") });
-const RestrictedNetworkPolicySchema = z.object({
-	mode: z.literal("restricted"),
-	allow: z.array(NetworkRuleSchema).max(256).default([])
-});
-const NetworkPolicySchema = z.preprocess((value) => value ?? { mode: "unrestricted" }, z.discriminatedUnion("mode", [UnrestrictedNetworkPolicySchema, RestrictedNetworkPolicySchema]));
-const NETWORK_STATES = [
-	"disabled",
-	"starting",
-	"ready",
-	"degraded"
-];
-const NetworkEventInputSchema = z.object({
-	source_seq: z.number().int().positive(),
-	occurred_at: z.iso.datetime(),
-	decision: z.enum(["allow", "deny"]),
-	transport: z.enum(["http", "https"]),
-	host: z.string().min(1).max(253),
-	port: z.number().int().min(1).max(65535),
-	method: z.string().max(32).nullable().default(null),
-	path: z.string().max(2048).refine((path) => !path.includes("?") && !path.includes("#"), "path cannot contain query or fragment").nullable().default(null),
-	matched_rule: z.string().max(512).nullable().default(null),
-	reason: z.string().min(1).max(128)
-});
-z.object({
-	source_session_id: z.uuid(),
-	events: z.array(NetworkEventInputSchema).min(1).max(100)
-});
-const NetworkEventSchema = NetworkEventInputSchema.omit({ source_seq: true }).extend({
-	seq: z.number().int().positive(),
-	workspace_id: z.uuid(),
-	source_session_id: z.uuid(),
-	source_seq: z.number().int().positive()
-});
-CursorQuerySchema(200, 100);
-const NetworkEventPageSchema = CursorPageSchema(NetworkEventSchema);
-//#endregion
-//#region ../contracts/src/workspace.ts
+//#region ../contracts/src/workspaces/workspace.ts
 const WORKSPACE_STATES = [
 	"queued",
 	"provisioning",
@@ -377,7 +661,7 @@ z.object({
 	cursor: z.string().optional()
 });
 //#endregion
-//#region ../contracts/src/api.ts
+//#region ../contracts/src/protocol/api.ts
 const TemplatePageSchema = CursorPageSchema(z.object({
 	name: z.string(),
 	version: z.string(),
@@ -438,161 +722,6 @@ const StoragePruneResultSchema = z.object({
 	skipped: z.number().int().nonnegative(),
 	transcripts_deleted: z.number().int().nonnegative()
 });
-//#endregion
-//#region ../contracts/src/attachment.ts
-const ATTACHMENT_MAX_FILE_BYTES = 26214400;
-const ATTACHMENT_CHUNK_BYTES = 524288;
-const AttachmentMediaTypeSchema = z.string().regex(/^[\w.+-]+\/[\w.+-]+$/).max(255);
-const AttachmentDescriptorSchema = z.object({
-	id: z.uuid(),
-	name: z.string().min(1).max(255),
-	path: z.string().min(1),
-	media_type: AttachmentMediaTypeSchema,
-	size_bytes: z.number().int().min(0).max(ATTACHMENT_MAX_FILE_BYTES),
-	sha256: z.string().regex(/^[0-9a-f]{64}$/)
-});
-z.looseObject({
-	type: z.literal("user"),
-	content: z.string(),
-	attachment_ids: z.array(z.uuid()).min(1).max(10).refine((ids) => new Set(ids).size === ids.length, "attachment_ids must be unique").optional()
-});
-const MANIFEST_OPEN = "<pocketcoder-attachments>";
-const MANIFEST_CLOSE = "</pocketcoder-attachments>";
-function splitAttachmentManifest(content) {
-	const open = content.lastIndexOf(MANIFEST_OPEN);
-	if (open < 0 || !content.trimEnd().endsWith(MANIFEST_CLOSE)) return {
-		text: content,
-		attachments: null
-	};
-	const close = content.lastIndexOf(MANIFEST_CLOSE);
-	const parsed = z.array(AttachmentDescriptorSchema).safeParse(safeJson(content.slice(open + 25, close)));
-	if (!parsed.success) return {
-		text: content,
-		attachments: null
-	};
-	return {
-		text: content.slice(0, open).trimEnd(),
-		attachments: parsed.data
-	};
-}
-function safeJson(value) {
-	try {
-		return JSON.parse(value);
-	} catch {
-		return;
-	}
-}
-const AttachmentStartPayload = z.object({
-	operation_id: z.uuid(),
-	attachment_id: z.uuid(),
-	name: z.string().min(1).max(255),
-	media_type: AttachmentMediaTypeSchema,
-	size_bytes: z.number().int().min(0).max(ATTACHMENT_MAX_FILE_BYTES)
-});
-const AttachmentChunkPayload = z.object({
-	operation_id: z.uuid(),
-	seq: z.number().int().nonnegative(),
-	content_b64: z.string().max(Math.ceil(ATTACHMENT_CHUNK_BYTES / 3) * 4 + 4)
-});
-const AttachmentFinishPayload = z.object({ operation_id: z.uuid() });
-const AttachmentAbortPayload = z.object({
-	operation_id: z.uuid(),
-	reason: z.string().max(512)
-});
-const AttachmentResolvePayload = z.object({
-	operation_id: z.uuid(),
-	attachment_ids: z.array(z.uuid()).min(1).max(10)
-});
-const AttachmentAckPayload = z.object({
-	operation_id: z.uuid(),
-	seq: z.number().int().nonnegative(),
-	received_bytes: z.number().int().nonnegative()
-});
-const AttachmentResultPayload = z.object({
-	operation_id: z.uuid(),
-	status: z.enum([
-		"created",
-		"existing",
-		"conflict",
-		"failed"
-	]),
-	descriptor: AttachmentDescriptorSchema.optional(),
-	failure_code: z.enum([
-		"invalid",
-		"too_large",
-		"sequence",
-		"io",
-		"interrupted"
-	]).optional(),
-	detail: z.string().max(512).optional()
-});
-const AttachmentResolvedPayload = z.object({
-	operation_id: z.uuid(),
-	descriptors: z.array(AttachmentDescriptorSchema).optional(),
-	missing_id: z.uuid().optional()
-});
-//#endregion
-//#region ../contracts/src/errors.ts
-const ERROR_CODES = {
-	"auth.invalid_key": 401,
-	"auth.missing_scope": 403,
-	"auth.disabled_principal": 403,
-	"validation.invalid": 400,
-	"idempotency.conflict": 409,
-	"capacity.queue_full": 429,
-	"capacity.waiters_full": 429,
-	"template.not_found": 404,
-	"template.version_not_found": 404,
-	"template.not_authorized": 403,
-	"workspace.not_found": 404,
-	"workspace.external_id_conflict": 409,
-	"workspace.not_ready": 409,
-	"workspace.terminal": 410,
-	"workspace.disconnected": 503,
-	"terminal.not_declared": 422,
-	"terminal.session_limit": 409,
-	"terminal.session_not_found": 404,
-	"terminal.session_closed": 409,
-	"terminal.protocol_unsupported": 426,
-	"workspace.persistence_not_enabled": 409,
-	"workspace.preserving": 409,
-	"checkpoint.not_found": 404,
-	"checkpoint.not_ready": 409,
-	"checkpoint.none_ready": 409,
-	"checkpoint.corrupt": 409,
-	"checkpoint.quota_exceeded": 413,
-	"checkpoint.in_use": 409,
-	"restore.template_not_authorized": 403,
-	"restore.image_unavailable": 409,
-	"restore.incompatible": 409,
-	"resume.unsupported": 409,
-	"conversation.expired": 410,
-	"conversation.deleted": 410,
-	"operation.conflict": 409,
-	"source.not_allowed": 422,
-	"source.invalid_revision": 422,
-	"secret.unavailable": 503,
-	"storage.capacity_exhausted": 507,
-	"relay.body_too_large": 413,
-	"relay.route_not_allowed": 422,
-	"relay.streaming_unsupported": 409,
-	"relay.deadline_exceeded": 504,
-	"relay.upstream_error": 502,
-	"attachment.invalid": 400,
-	"attachment.too_large": 413,
-	"attachment.not_found": 404,
-	"attachment.conflict": 409,
-	"attachment.unsupported": 409,
-	"attachment.interrupted": 503,
-	"internal.error": 500
-};
-const errorCodes = Object.keys(ERROR_CODES);
-const ErrorEnvelopeSchema = z.object({ error: z.object({
-	code: z.enum(errorCodes),
-	message: z.string().min(1),
-	request_id: z.string().min(1),
-	details: z.record(z.string(), z.unknown()).optional()
-}) });
 WORKSPACE_STATES.map((s) => `workspace.${s}`);
 z.object({
 	id: z.uuid(),
@@ -624,7 +753,7 @@ z.object({
 	})
 });
 //#endregion
-//#region ../contracts/src/logs.ts
+//#region ../contracts/src/protocol/logs.ts
 const LogChunkSchema = z.object({
 	seq: z.number().int().positive(),
 	stream: z.string(),
@@ -634,47 +763,14 @@ const LogChunkSchema = z.object({
 CursorQuerySchema(1e3, 200);
 const LogPageSchema = CursorPageSchema(LogChunkSchema);
 //#endregion
-//#region ../contracts/src/protocol-stream.ts
-const ProxyStreamStartPayload = z.object({
-	request_id: z.uuid(),
-	status: z.number().int().min(100).max(599),
-	headers: z.record(z.string(), z.string())
-});
-const ProxyStreamChunkPayload = z.object({
-	request_id: z.uuid(),
-	seq: z.number().int().nonnegative(),
-	content_b64: z.string().max(87400)
-});
-const ProxyStreamEndPayload = z.object({
-	request_id: z.uuid(),
-	error_code: z.enum([
-		"unreachable",
-		"deadline",
-		"too_large"
-	]).optional()
-});
-const ProxyStreamAckPayload = z.object({
-	request_id: z.uuid(),
-	seq: z.number().int().nonnegative()
-});
-const ProxyStreamCancelPayload = z.object({
-	request_id: z.uuid(),
-	reason: z.enum([
-		"downstream_closed",
-		"deadline",
-		"too_large",
-		"workspace_disconnected"
-	])
-});
-//#endregion
-//#region ../contracts/src/template-constants.ts
+//#region ../contracts/src/templates/template-constants.ts
 function isAbsolutePath(value) {
 	return value.startsWith("/") && ![...value].some((character) => character.codePointAt(0) === 0);
 }
 const SECRET_ENV_PATTERN = /(SECRET|TOKEN|PASSWORD|PASSWD|API_?KEY|PRIVATE_?KEY|CREDENTIAL)/i;
 const SECRET_REFERENCE_PREFIX = "secretRef:";
 //#endregion
-//#region ../contracts/src/template-schema.ts
+//#region ../contracts/src/templates/template-schema.ts
 const NAME_RE = /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$/;
 const SEMVER_RE = /^\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?$/;
 const IMAGE_DIGEST_RE = /^[^\s@]+@sha256:[0-9a-f]{64}$/;
@@ -864,7 +960,7 @@ const TemplateManifestBaseSchema = z.object({
 	spec: TemplateSpecSchema
 });
 //#endregion
-//#region ../contracts/src/template-runtime.ts
+//#region ../contracts/src/templates/template-runtime.ts
 const LEGACY_AGENTAPI_SERVICE = ServiceSchema.parse({
 	baseUrl: "http://127.0.0.1:3284",
 	routes: [
@@ -920,7 +1016,7 @@ function templateServices(spec) {
 	return isAgentApiNative(spec) ? { agent: AGENTAPI_SERVICE } : spec.services;
 }
 //#endregion
-//#region ../contracts/src/template-validation.ts
+//#region ../contracts/src/templates/template-validation.ts
 function envSources(spec) {
 	const sources = [[["spec", "env"], spec.env], [isAgentApiNative(spec) ? [
 		"spec",
@@ -1259,12 +1355,14 @@ TemplateManifestBaseSchema.superRefine((manifest, ctx) => {
 	validateTemplateSpec(manifest.spec, ctx);
 });
 //#endregion
-//#region ../contracts/src/terminal.ts
+//#region ../contracts/src/terminals/terminal.ts
 const TERMINAL_CHUNK_BYTES = 32768;
 const TERMINAL_REPLAY_BUFFER_BYTES = 65536;
 function base64Schema(maxBytes) {
 	return z.string().regex(/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/).refine((value) => {
-		const padding = value.endsWith("==") ? 2 : value.endsWith("=") ? 1 : 0;
+		let padding = 0;
+		if (value.endsWith("==")) padding = 2;
+		else if (value.endsWith("=")) padding = 1;
 		return value.length / 4 * 3 - padding <= maxBytes;
 	}, `decoded payload must not exceed ${maxBytes} bytes`);
 }
@@ -1368,8 +1466,41 @@ const TerminalSessionSchema = z.object({
 	bytes_in: z.number().int().nonnegative(),
 	bytes_out: z.number().int().nonnegative()
 });
-CursorQuerySchema(200, 50);
-const TerminalSessionPageSchema = CursorPageSchema(TerminalSessionSchema);
+CursorQuerySchema(200, 50);
+const TerminalSessionPageSchema = CursorPageSchema(TerminalSessionSchema);
+//#endregion
+//#region ../contracts/src/protocol/protocol-stream.ts
+const ProxyStreamStartPayload = z.object({
+	request_id: z.uuid(),
+	status: z.number().int().min(100).max(599),
+	headers: z.record(z.string(), z.string())
+});
+const ProxyStreamChunkPayload = z.object({
+	request_id: z.uuid(),
+	seq: z.number().int().nonnegative(),
+	content_b64: z.string().max(87400)
+});
+const ProxyStreamEndPayload = z.object({
+	request_id: z.uuid(),
+	error_code: z.enum([
+		"unreachable",
+		"deadline",
+		"too_large"
+	]).optional()
+});
+const ProxyStreamAckPayload = z.object({
+	request_id: z.uuid(),
+	seq: z.number().int().nonnegative()
+});
+const ProxyStreamCancelPayload = z.object({
+	request_id: z.uuid(),
+	reason: z.enum([
+		"downstream_closed",
+		"deadline",
+		"too_large",
+		"workspace_disconnected"
+	])
+});
 const ProviderInputSchema = z.object({
 	workspace_id: z.uuid(),
 	server_url: z.string(),
@@ -1779,7 +1910,7 @@ z.discriminatedUnion("type", [
 	})
 ]);
 //#endregion
-//#region src/admin.ts
+//#region src/resources/admin/admin.ts
 var AdministrationApi = class {
 	transport;
 	constructor(transport) {
@@ -1799,7 +1930,7 @@ var AdministrationApi = class {
 	}
 };
 //#endregion
-//#region src/errors.ts
+//#region src/transport/errors.ts
 z.enum(["client.non_json_response", "client.invalid_response"]);
 var PocketCoderError = class extends Error {
 	code;
@@ -1856,7 +1987,7 @@ function responseError(response, body) {
 	});
 }
 //#endregion
-//#region src/attachments.ts
+//#region src/resources/attachments/attachments.ts
 const DEFAULT_READY_TIMEOUT_MS = 12e4;
 function contentDisposition(name) {
 	const clean = name.replace(/[\r\n]/g, "");
@@ -1929,7 +2060,7 @@ var AgentApi = class {
 	}
 };
 //#endregion
-//#region src/common.ts
+//#region src/transport/common.ts
 function queryString(values) {
 	const params = new URLSearchParams();
 	for (const [key, value] of Object.entries(values)) if (value !== void 0) params.set(key, String(value));
@@ -1942,7 +2073,7 @@ function page(body) {
 	};
 }
 //#endregion
-//#region src/checkpoints.ts
+//#region src/resources/checkpoints/checkpoints.ts
 var CheckpointsApi = class {
 	transport;
 	constructor(transport) {
@@ -1990,21 +2121,33 @@ var OperationsApi = class {
 	}
 };
 //#endregion
-//#region src/conversations.ts
+//#region src/resources/conversations/conversations.ts
 var ConversationsApi = class {
 	transport;
 	constructor(transport) {
 		this.transport = transport;
 	}
 	async list(id, query = {}, options = {}) {
-		return page(await this.transport.request(`/v1/workspaces/${encodeURIComponent(id)}/conversation?${queryString({
+		const body = await this.transport.request(`/v1/workspaces/${encodeURIComponent(id)}/conversation?${queryString({
 			cursor: query.cursor,
 			limit: query.limit ?? 100
-		})}`, ConversationPageSchema, options));
+		})}`, ConversationPageSchema, options);
+		return {
+			...page(body),
+			protocol: body.protocol,
+			retention: body.retention
+		};
+	}
+	async acceptRequest(id, identity, options = {}) {
+		return this.transport.request(`/v1/workspaces/${encodeURIComponent(id)}/conversation/requests`, ConversationRequestReceiptSchema, {
+			...options,
+			method: "POST",
+			body: JSON.stringify(identity)
+		});
 	}
 };
 //#endregion
-//#region src/diagnostics.ts
+//#region src/resources/diagnostics/diagnostics.ts
 var WorkspaceCursorApi = class {
 	transport;
 	resource;
@@ -2037,7 +2180,69 @@ var OutputsApi = class extends WorkspaceCursorApi {
 	}
 };
 //#endregion
-//#region src/templates.ts
+//#region src/resources/keys/keys.ts
+var KeysApi = class {
+	transport;
+	constructor(transport) {
+		this.transport = transport;
+	}
+	list(principalId, query = {}, options = {}) {
+		return this.transport.request(`/v1/principals/${encodeURIComponent(principalId)}/keys?${queryString({
+			limit: query.limit,
+			cursor: query.cursor,
+			request_id: query.requestId
+		})}`, KeyListResponseSchema, options);
+	}
+	async *all(principalId, query = {}, options = {}) {
+		let cursor;
+		do {
+			const page = await this.list(principalId, {
+				...query,
+				cursor
+			}, options);
+			yield* page.items;
+			cursor = page.next_cursor ?? void 0;
+		} while (cursor);
+	}
+	issue(principalId, input, options = {}) {
+		return this.transport.request(`/v1/principals/${encodeURIComponent(principalId)}/keys`, KeyIssueResponseSchema, {
+			method: "POST",
+			body: JSON.stringify(input),
+			signal: options.signal
+		});
+	}
+	revoke(principalId, keyId, options = {}) {
+		return this.transport.request(`/v1/principals/${encodeURIComponent(principalId)}/keys/${encodeURIComponent(keyId)}`, z.object({ revoked: z.literal(true) }), {
+			method: "DELETE",
+			signal: options.signal
+		});
+	}
+	revokeAll(principalId, options = {}) {
+		return this.transport.request(`/v1/principals/${encodeURIComponent(principalId)}/keys`, z.object({ revoked: z.literal(true) }), {
+			method: "DELETE",
+			signal: options.signal
+		});
+	}
+};
+var RecoveryApi = class {
+	transport;
+	constructor(transport) {
+		this.transport = transport;
+	}
+	purge(principalId, workspaceId, executionKey, options = {}) {
+		return this.transport.request(`/v1/principals/${encodeURIComponent(principalId)}/workspaces/${encodeURIComponent(workspaceId)}/purge`, OperationResourceSchema, {
+			method: "POST",
+			headers: { "Idempotency-Key": executionKey },
+			body: "{}",
+			signal: options.signal
+		});
+	}
+	operation(principalId, operationId, options = {}) {
+		return this.transport.request(`/v1/principals/${encodeURIComponent(principalId)}/operations/${encodeURIComponent(operationId)}`, OperationResourceSchema, options);
+	}
+};
+//#endregion
+//#region src/resources/templates/templates.ts
 var TemplatesApi = class {
 	transport;
 	constructor(transport) {
@@ -2054,7 +2259,7 @@ var TemplatesApi = class {
 	}
 };
 //#endregion
-//#region src/terminals.ts
+//#region src/resources/terminals/terminals.ts
 var TerminalConnection = class {
 	socket;
 	messageListeners = /* @__PURE__ */ new Set();
@@ -2156,7 +2361,109 @@ var TerminalsApi = class {
 	}
 };
 //#endregion
-//#region src/transport.ts
+//#region src/resources/workspaces/workspaces.ts
+const TERMINAL_WORKSPACE_STATES = new Set(TERMINAL_STATES);
+var WorkspacesApi = class {
+	transport;
+	constructor(transport) {
+		this.transport = transport;
+	}
+	async list(query = {}, options = {}) {
+		return page(await this.transport.request(`/v1/workspaces?${queryString({
+			state: query.state,
+			template: query.template,
+			external_id: query.externalId,
+			limit: query.limit ?? 50,
+			cursor: query.cursor
+		})}`, WorkspacePageSchema, options));
+	}
+	async *all(query = {}, options = {}) {
+		let cursor;
+		do {
+			const current = await this.list({
+				...query,
+				cursor
+			}, options);
+			for (const workspace of current.items) yield workspace;
+			cursor = current.nextCursor ?? void 0;
+		} while (cursor);
+	}
+	get(id, options = {}) {
+		return this.transport.request(`/v1/workspaces/${encodeURIComponent(id)}`, WorkspaceResourceSchema, options);
+	}
+	create(input, options = {}) {
+		const body = {
+			external_id: input.externalId,
+			template: {
+				name: input.templateName,
+				...input.templateVersion ? { version: input.templateVersion } : {}
+			},
+			...input.launchInput ? { launch_input: input.launchInput } : {},
+			...input.metadata ? { metadata: input.metadata } : {},
+			...input.source ? { source: input.source } : {}
+		};
+		return this.transport.request("/v1/workspaces", WorkspaceResourceSchema, {
+			method: "POST",
+			signal: options.signal,
+			headers: { "Idempotency-Key": input.idempotencyKey ?? input.externalId },
+			body: JSON.stringify(body)
+		});
+	}
+	cancel(id, options = {}) {
+		return this.transport.request(`/v1/workspaces/${encodeURIComponent(id)}/cancel`, WorkspaceResourceSchema, {
+			method: "POST",
+			signal: options.signal
+		});
+	}
+	change(id, after, wait, options = {}) {
+		return this.transport.request(`/v1/workspaces/${encodeURIComponent(id)}/changes?after=${after}&wait=${wait}`, WorkspaceChangeSchema, options);
+	}
+	async waitForReady(initial, timeoutMs, options = {}) {
+		const deadline = Date.now() + timeoutMs;
+		let workspace = initial;
+		while (workspace.state !== "ready") {
+			if (TERMINAL_STATES.includes(workspace.state)) throw new WorkspaceTerminalError(workspace);
+			const remainingMs = deadline - Date.now();
+			if (remainingMs <= 0) throw new Error(`workspace ${workspace.id} did not become ready within ${timeoutMs}ms`);
+			workspace = (await this.change(workspace.id, workspace.change_cursor, Math.max(1, Math.min(30, Math.ceil(remainingMs / 1e3))), options)).workspace;
+			options.onTick?.(workspace);
+		}
+		return workspace;
+	}
+	async waitForAgentInput(id, timeoutMs, options = {}) {
+		const deadline = Date.now() + timeoutMs;
+		let workspace = await this.get(id, options);
+		while (workspace.agent_state !== "stable") {
+			if (TERMINAL_STATES.includes(workspace.state)) throw new WorkspaceTerminalError(workspace);
+			const remainingMs = deadline - Date.now();
+			if (remainingMs <= 0) throw new AgentNotReadyError(workspace.id, workspace.agent_state, timeoutMs);
+			workspace = (await this.change(workspace.id, workspace.change_cursor, Math.max(1, Math.min(30, Math.ceil(remainingMs / 1e3))), options)).workspace;
+		}
+		return workspace;
+	}
+	preserve(id, input, key, options = {}) {
+		return this.jsonOperation(`/v1/workspaces/${encodeURIComponent(id)}/preserve`, input, key, PreserveResponseSchema, options);
+	}
+	purge(id, key, options = {}) {
+		return this.jsonOperation(`/v1/workspaces/${encodeURIComponent(id)}/purge`, {}, key, OperationResourceSchema, options);
+	}
+	recreate(id, input, key, options = {}) {
+		return this.jsonOperation(`/v1/workspaces/${encodeURIComponent(id)}/recreate`, input, key, RestoreResponseSchema, options);
+	}
+	resume(id, input, key, options = {}) {
+		return this.jsonOperation(`/v1/workspaces/${encodeURIComponent(id)}/resume`, input, key, ResumeResponseSchema, options);
+	}
+	jsonOperation(path, input, key, schema, options) {
+		return this.transport.request(path, schema, {
+			method: "POST",
+			signal: options.signal,
+			headers: { "Idempotency-Key": key },
+			body: JSON.stringify(input)
+		});
+	}
+};
+//#endregion
+//#region src/transport/transport.ts
 function baseUrlOf(value) {
 	let url;
 	try {
@@ -2273,105 +2580,6 @@ async function delay(milliseconds, signal) {
 	});
 }
 //#endregion
-//#region src/workspaces.ts
-const TERMINAL_WORKSPACE_STATES = new Set(TERMINAL_STATES);
-var WorkspacesApi = class {
-	transport;
-	constructor(transport) {
-		this.transport = transport;
-	}
-	async list(query = {}, options = {}) {
-		return page(await this.transport.request(`/v1/workspaces?${queryString({
-			state: query.state,
-			template: query.template,
-			external_id: query.externalId,
-			limit: query.limit ?? 50,
-			cursor: query.cursor
-		})}`, WorkspacePageSchema, options));
-	}
-	async *all(query = {}, options = {}) {
-		let cursor;
-		do {
-			const current = await this.list({
-				...query,
-				cursor
-			}, options);
-			for (const workspace of current.items) yield workspace;
-			cursor = current.nextCursor ?? void 0;
-		} while (cursor);
-	}
-	get(id, options = {}) {
-		return this.transport.request(`/v1/workspaces/${encodeURIComponent(id)}`, WorkspaceResourceSchema, options);
-	}
-	create(input, options = {}) {
-		const body = {
-			external_id: input.externalId,
-			template: {
-				name: input.templateName,
-				...input.templateVersion ? { version: input.templateVersion } : {}
-			},
-			...input.launchInput ? { launch_input: input.launchInput } : {},
-			...input.metadata ? { metadata: input.metadata } : {},
-			...input.source ? { source: input.source } : {}
-		};
-		return this.transport.request("/v1/workspaces", WorkspaceResourceSchema, {
-			method: "POST",
-			signal: options.signal,
-			headers: { "Idempotency-Key": input.idempotencyKey ?? input.externalId },
-			body: JSON.stringify(body)
-		});
-	}
-	cancel(id, options = {}) {
-		return this.transport.request(`/v1/workspaces/${encodeURIComponent(id)}/cancel`, WorkspaceResourceSchema, {
-			method: "POST",
-			signal: options.signal
-		});
-	}
-	change(id, after, wait, options = {}) {
-		return this.transport.request(`/v1/workspaces/${encodeURIComponent(id)}/changes?after=${after}&wait=${wait}`, WorkspaceChangeSchema, options);
-	}
-	async waitForReady(initial, timeoutMs, options = {}) {
-		const deadline = Date.now() + timeoutMs;
-		let workspace = initial;
-		while (workspace.state !== "ready") {
-			if (TERMINAL_STATES.includes(workspace.state)) throw new WorkspaceTerminalError(workspace);
-			const remainingMs = deadline - Date.now();
-			if (remainingMs <= 0) throw new Error(`workspace ${workspace.id} did not become ready within ${timeoutMs}ms`);
-			workspace = (await this.change(workspace.id, workspace.change_cursor, Math.max(1, Math.min(30, Math.ceil(remainingMs / 1e3))), options)).workspace;
-			options.onTick?.(workspace);
-		}
-		return workspace;
-	}
-	async waitForAgentInput(id, timeoutMs, options = {}) {
-		const deadline = Date.now() + timeoutMs;
-		let workspace = await this.get(id, options);
-		while (workspace.agent_state !== "stable") {
-			if (TERMINAL_STATES.includes(workspace.state)) throw new WorkspaceTerminalError(workspace);
-			const remainingMs = deadline - Date.now();
-			if (remainingMs <= 0) throw new AgentNotReadyError(workspace.id, workspace.agent_state, timeoutMs);
-			workspace = (await this.change(workspace.id, workspace.change_cursor, Math.max(1, Math.min(30, Math.ceil(remainingMs / 1e3))), options)).workspace;
-		}
-		return workspace;
-	}
-	preserve(id, input, key, options = {}) {
-		return this.jsonOperation(`/v1/workspaces/${encodeURIComponent(id)}/preserve`, input, key, PreserveResponseSchema, options);
-	}
-	recreate(id, input, key, options = {}) {
-		return this.jsonOperation(`/v1/workspaces/${encodeURIComponent(id)}/recreate`, input, key, RestoreResponseSchema, options);
-	}
-	resume(id, input, key, options = {}) {
-		return this.jsonOperation(`/v1/workspaces/${encodeURIComponent(id)}/resume`, input, key, ResumeResponseSchema, options);
-	}
-	jsonOperation(path, input, key, schema, options) {
-		return this.transport.request(path, schema, {
-			method: "POST",
-			signal: options.signal,
-			headers: { "Idempotency-Key": key },
-			body: JSON.stringify(input)
-		});
-	}
-};
-//#endregion
 //#region src/client.ts
 var PocketCoderClient = class {
 	transport;
@@ -2387,6 +2595,8 @@ var PocketCoderClient = class {
 	outputs;
 	administration;
 	terminals;
+	keys;
+	recovery;
 	constructor(config, fetchImpl = fetch) {
 		this.transport = new PocketCoderTransport(config, fetchImpl);
 		this.templates = new TemplatesApi(this.transport);
@@ -2401,13 +2611,15 @@ var PocketCoderClient = class {
 		this.outputs = new OutputsApi(this.transport);
 		this.administration = new AdministrationApi(this.transport);
 		this.terminals = new TerminalsApi(this.transport);
+		this.keys = new KeysApi(this.transport);
+		this.recovery = new RecoveryApi(this.transport);
 	}
 	raw(path, init = {}) {
 		return this.transport.raw(path, init);
 	}
 };
 //#endregion
-//#region src/workspace-turn-resolver.ts
+//#region src/resources/workspaces/workspace-turn-resolver.ts
 const ERROR_MESSAGES = {
 	not_resumable: "workspace cannot be resumed",
 	resume_handler_missing: "workspace resume handler is not configured",
@@ -2551,4 +2763,4 @@ var WorkspaceTurnResolver = class {
 	}
 };
 //#endregion
-export { AdministrationApi, AgentApi, AgentNotReadyError, AttachmentsApi, CheckpointsApi, ConversationGoneError, ConversationsApi, LogsApi, NetworkEventsApi, OperationsApi, OutputsApi, PocketCoderClient, PocketCoderError, TERMINAL_WORKSPACE_STATES, TemplatesApi, TerminalConnection, TerminalsApi, WorkspaceTerminalError, WorkspaceTurnResolutionError, WorkspaceTurnResolver, WorkspacesApi, isPocketCoderErrorCode, splitAttachmentManifest };
+export { AdministrationApi, AgentApi, AgentNotReadyError, AttachmentsApi, CheckpointsApi, ConversationGoneError, ConversationsApi, KeysApi, LogsApi, NetworkEventsApi, OperationsApi, OutputsApi, PocketCoderClient, PocketCoderError, RecoveryApi, TERMINAL_WORKSPACE_STATES, TemplatesApi, TerminalConnection, TerminalsApi, WorkspaceTerminalError, WorkspaceTurnResolutionError, WorkspaceTurnResolver, WorkspacesApi, isPocketCoderErrorCode, splitAttachmentManifest };