@arnilo/prism-tools 0.0.0-stage → 0.13.1

package/work/src/connectors/tool-helpers.ts

@@ -0,0 +1,398 @@
+import { type JsonObject, type ToolDefinition, type ToolExecutionContext, type ToolResult, UNTRUSTED_EXTERNAL_TRUST } from "@arnilo/prism";
+import { type ArtifactBodyRef } from "@arnilo/prism/artifacts";
+import { resolveSandboxPath } from "../tools/filesystem.js";
+import { computePayloadDigest, extractDraftRecipients, validateApproval } from "./drafts.js";
+import { WorkToolError } from "./errors.js";
+import { artifactRef, readUploadBytes, sha256 } from "./file-bytes.js";
+import { identityKey } from "./idempotency.js";
+import { assertIdentityActive } from "./identity.js";
+import { resolveWorkLimits } from "./limits.js";
+import type {
+  GoogleWorkspaceAdapter,
+  Microsoft365Adapter,
+  WorkApprovalCheckInput,
+  WorkDraft,
+  WorkDraftApproval,
+  WorkMutationRecord,
+  WorkProvider,
+  WorkToolsOptions,
+} from "./types.js";
+export function objectSchema(properties: JsonObject, required: readonly string[]): JsonObject {
+  return { type: "object", properties, required: [...required], additionalProperties: false };
+}
+
+export function reqString(args: JsonObject, key: string): string {
+  const value = args[key];
+  if (typeof value !== "string" || !value) throw new WorkToolError("ERR_PRISM_WORK_INPUT", `${key} must be a non-empty string`);
+  return value;
+}
+
+export function optString(args: JsonObject, key: string): string | undefined {
+  const value = args[key];
+  if (value === undefined) return undefined;
+  if (typeof value !== "string") throw new WorkToolError("ERR_PRISM_WORK_INPUT", `${key} must be a string`);
+  return value;
+}
+
+export const ARTIFACT: JsonObject = {
+  type: "object",
+  properties: {
+    tenantId: { type: "string" },
+    accountId: { type: "string" },
+    userId: { type: "string" },
+    artifactId: { type: "string" },
+    threadId: { type: "string" },
+    version: { type: "integer", minimum: 1 },
+    mime: { type: "string" },
+    size: { type: "integer", minimum: 0 },
+    hash: { type: "string", pattern: "^[0-9a-f]{64}$" },
+  },
+  required: ["tenantId", "artifactId", "threadId", "version", "mime", "size", "hash"],
+  additionalProperties: false,
+};
+
+function artifactJson(ref: ArtifactBodyRef): JsonObject {
+  const tenantId = ref.tenantId;
+  const accountId = ref.accountId;
+  const userId = ref.userId;
+  return {
+    ...(tenantId === undefined ? {} : { tenantId }),
+    ...(accountId === undefined ? {} : { accountId }),
+    ...(userId === undefined ? {} : { userId }),
+    artifactId: ref.artifactId,
+    threadId: ref.threadId,
+    version: ref.version,
+    mime: ref.mime,
+    size: ref.size,
+    hash: ref.hash,
+  };
+}
+
+export function sourceCount(args: JsonObject): number {
+  return Number(args.filePath !== undefined) + Number(args.artifact !== undefined) + Number(args.sandboxPath !== undefined);
+}
+
+function fileLimit(options: WorkToolsOptions): number {
+  return resolveWorkLimits(options.limits).maxFileBytes;
+}
+
+export async function fileDraftPayload(
+  options: WorkToolsOptions,
+  provider: WorkProvider,
+  args: JsonObject,
+  context: ToolExecutionContext,
+): Promise<JsonObject> {
+  if (sourceCount(args) !== 1) throw new WorkToolError("ERR_PRISM_WORK_INPUT", "provide exactly one of filePath, artifact, or sandboxPath");
+  const maxBytes = fileLimit(options);
+  const { sandboxPath, ...payload } = args;
+  if (args.artifact !== undefined) {
+    const artifact = artifactRef(args.artifact);
+    if (artifact.size > maxBytes) throw new WorkToolError("ERR_PRISM_WORK_LIMIT", "File exceeds byte limit");
+    if (provider === "microsoft365") reqString(args, "name");
+    return { ...payload, artifact: artifactJson(artifact), contentHash: artifact.hash, byteLength: artifact.size };
+  }
+  if (sandboxPath !== undefined) {
+    if (typeof sandboxPath !== "string" || !sandboxPath)
+      throw new WorkToolError("ERR_PRISM_WORK_INPUT", "sandboxPath must be a non-empty string");
+    if (!options.filesystem) throw new WorkToolError("ERR_PRISM_WORK_INPUT", "sandboxPath requires a configured filesystem");
+    const filePath = await resolveSandboxPath(options.filesystem, sandboxPath);
+    const bytes = await options.filesystem.readFile(filePath, { maxBytes, signal: context.signal });
+    if (bytes.byteLength > maxBytes) throw new WorkToolError("ERR_PRISM_WORK_LIMIT", "File exceeds byte limit");
+    const contentHash = sha256(bytes);
+    if (!options.artifacts) return { ...payload, filePath, contentHash, byteLength: bytes.byteLength };
+    const artifact = options.artifacts.createRef({
+      context,
+      provider,
+      mime: "application/octet-stream",
+      byteLength: bytes.byteLength,
+      contentHash,
+    });
+    await options.artifacts.bodies.put(artifact, bytes, { signal: context.signal });
+    if (provider === "microsoft365") reqString(args, "name");
+    return { ...payload, artifact: artifactJson(artifact), contentHash, byteLength: bytes.byteLength };
+  }
+  const source = await readUploadBytes(args, undefined, maxBytes, context.signal);
+  return { ...payload, contentHash: source.contentHash, byteLength: source.bytes.byteLength };
+}
+
+export async function fileGet(
+  options: WorkToolsOptions,
+  adapter: WorkAdapter,
+  provider: WorkProvider,
+  args: JsonObject,
+  context: ToolExecutionContext,
+): Promise<JsonObject> {
+  const itemId = reqString(args, "id");
+  const destPath = optString(args, "destPath");
+  if (destPath === "") throw new WorkToolError("ERR_PRISM_WORK_INPUT", "destPath must be a non-empty string");
+  if (!destPath && !options.artifacts)
+    throw new WorkToolError("ERR_PRISM_WORK_INPUT", "file get requires destPath or a configured artifact store");
+  if (!options.scanAttachment) throw new WorkToolError("ERR_PRISM_WORK_POLICY", "file get requires an attachment scan");
+  const raw = await adapter.runOp("file.get" as never, { id: itemId }, context.signal);
+  if (!(raw instanceof Uint8Array)) throw new WorkToolError("ERR_PRISM_WORK_HTTP", "Connector file download was not bytes");
+  const maxBytes = fileLimit(options);
+  if (raw.byteLength > maxBytes) throw new WorkToolError("ERR_PRISM_WORK_LIMIT", "File exceeds byte limit");
+  await options.scanAttachment({ bytes: raw.byteLength, name: itemId });
+  const contentHash = sha256(raw);
+  const artifacts = options.artifacts;
+  const artifact = artifacts?.createRef({
+    context,
+    provider,
+    itemId,
+    mime: "application/octet-stream",
+    byteLength: raw.byteLength,
+    contentHash,
+  });
+  if (artifact && artifacts) await artifacts.bodies.put(artifact, raw, { signal: context.signal });
+  const path =
+    destPath === undefined
+      ? undefined
+      : await (async () => {
+          if (!options.filesystem) throw new WorkToolError("ERR_PRISM_WORK_INPUT", "destPath requires a configured filesystem");
+          const target = await resolveSandboxPath(options.filesystem, destPath);
+          await options.filesystem.writeFile(target, raw, { maxBytes, signal: context.signal });
+          return target;
+        })();
+  return {
+    ...(artifact === undefined ? {} : { artifact: artifactJson(artifact) }),
+    ...(path === undefined ? {} : { path }),
+    byteLength: raw.byteLength,
+    contentHash,
+    untrusted: true,
+  };
+}
+
+export function result(context: ToolExecutionContext, name: string, provider: WorkProvider, value: unknown): ToolResult {
+  // No banner here: the kernel wraps untrusted results (UNTRUSTED_EXTERNAL_TRUST) in its envelope.
+  return { toolCallId: context.toolCallId, name, value, metadata: { trust: UNTRUSTED_EXTERNAL_TRUST, provider } };
+}
+
+export function splitAddresses(value: string): string[] {
+  return value
+    .split(",")
+    .map((part) => part.trim())
+    .filter(Boolean);
+}
+
+export function assertExternalAllowed(options: WorkToolsOptions, addresses: readonly string[]): void {
+  const policy = options.externalRecipients;
+  for (const address of addresses) {
+    if (!policy?.allow(address)) {
+      throw new WorkToolError("ERR_PRISM_WORK_POLICY", `External recipient denied: ${address}`);
+    }
+  }
+}
+
+type WorkAdapter = Microsoft365Adapter | GoogleWorkspaceAdapter;
+
+export async function executeApprovedMutation(
+  options: WorkToolsOptions,
+  adapter: WorkAdapter,
+  op: string,
+  payload: JsonObject,
+  context: ToolExecutionContext,
+): Promise<unknown> {
+  const draftId = typeof payload.draftId === "string" && payload.draftId.trim() ? payload.draftId.trim() : undefined;
+  const expectedRevision = typeof payload.revision === "number" ? payload.revision : undefined;
+  const { draftId: _d, revision: _r, idempotencyKey: _i, ...cleanPayload } = payload;
+
+  let draft: WorkDraft;
+  if (draftId) {
+    const existingRes = adapter.getDraft(draftId);
+    const existing = existingRes instanceof Promise ? await existingRes : existingRes;
+    if (!existing) {
+      throw new WorkToolError("ERR_PRISM_WORK_DRAFT", `Draft ${draftId} not found`);
+    }
+    if (existing.identityKey !== identityKey(adapter.identity)) {
+      throw new WorkToolError("ERR_PRISM_WORK_IDENTITY", "Draft identity mismatch");
+    }
+    if (expectedRevision !== undefined && existing.revision !== expectedRevision) {
+      throw new WorkToolError(
+        "ERR_PRISM_WORK_DRAFT_STALE",
+        `Draft revision mismatch (expected ${expectedRevision}, got ${existing.revision})`,
+      );
+    }
+    if (existing.status === "executed") {
+      throw new WorkToolError("ERR_PRISM_WORK_DRAFT_EXECUTED", "Draft already executed");
+    }
+    if (existing.status === "unknown") {
+      throw new WorkToolError("ERR_PRISM_WORK_IDEMPOTENCY_UNKNOWN", "Draft outcome is unknown and requires reconciliation");
+    }
+
+    const hasKeys = Object.keys(cleanPayload).length > 0;
+    const mergedPayload: JsonObject = hasKeys ? { ...existing.payload, ...cleanPayload } : existing.payload;
+    const isModified = hasKeys && computePayloadDigest(mergedPayload) !== existing.payloadDigest;
+
+    if (isModified) {
+      const newRecipients = extractDraftRecipients(mergedPayload);
+      if (newRecipients.length > 0) {
+        assertExternalAllowed(options, newRecipients);
+      }
+      if (adapter.updateDraft) {
+        const updateRes = adapter.updateDraft(existing.draftId, mergedPayload, { expectedRevision: existing.revision });
+        draft = updateRes instanceof Promise ? await updateRes : updateRes;
+      } else {
+        const createRes = adapter.createDraft(op as never, mergedPayload);
+        draft = createRes instanceof Promise ? await createRes : createRes;
+      }
+    } else {
+      draft = existing;
+    }
+  } else {
+    const recipients = extractDraftRecipients(cleanPayload);
+    if (recipients.length > 0) {
+      assertExternalAllowed(options, recipients);
+    }
+    const createRes = adapter.createDraft(op as never, cleanPayload);
+    draft = createRes instanceof Promise ? await createRes : createRes;
+  }
+
+  let approved = false;
+  if (options.approval) {
+    const checkInput: WorkApprovalCheckInput = {
+      draftId: draft.draftId,
+      op,
+      identity: adapter.identity,
+      revision: draft.revision,
+      payloadDigest: draft.payloadDigest,
+      recipients: draft.recipients,
+      policyRevision: draft.policyRevision,
+    };
+    const decisionRes = options.approval.isApproved(checkInput);
+    const decision = decisionRes instanceof Promise ? await decisionRes : decisionRes;
+    if (decision === true) {
+      approved = true;
+      const approval: WorkDraftApproval = {
+        draftId: draft.draftId,
+        revision: draft.revision,
+        payloadDigest: draft.payloadDigest,
+        identityKey: draft.identityKey,
+        policyRevision: draft.policyRevision,
+        approvedAt: new Date().toISOString(),
+      };
+      if (adapter.approveDraft) {
+        const appRes = adapter.approveDraft(approval);
+        draft = appRes instanceof Promise ? await appRes : appRes;
+      } else {
+        const markRes = adapter.markDraft(draft.draftId, "approved");
+        draft = markRes instanceof Promise ? await markRes : markRes;
+      }
+    } else if (typeof decision === "object" && decision !== null) {
+      validateApproval(draft, decision, { policyRevision: draft.policyRevision });
+      approved = true;
+      if (adapter.approveDraft) {
+        const appRes = adapter.approveDraft(decision);
+        draft = appRes instanceof Promise ? await appRes : appRes;
+      } else {
+        const markRes = adapter.markDraft(draft.draftId, "approved");
+        draft = markRes instanceof Promise ? await markRes : markRes;
+      }
+    }
+  } else if (draft.status === "approved") {
+    approved = true;
+  }
+
+  if (!approved || draft.status !== "approved") {
+    return {
+      draftId: draft.draftId,
+      revision: draft.revision,
+      payloadDigest: draft.payloadDigest,
+      status: "pending_approval",
+      untrusted: true,
+    };
+  }
+
+  if (draft.approval) {
+    validateApproval(draft, draft.approval, { policyRevision: draft.policyRevision });
+  }
+  assertIdentityActive(adapter.identity);
+
+  const idempotencyKey = context.idempotencyKey;
+  const store = options.idempotencyStore;
+  if (!idempotencyKey || !store) {
+    throw new WorkToolError("ERR_PRISM_WORK_IDEMPOTENCY", "approved mutation requires core idempotency key and store");
+  }
+  const claim = await store.begin({ identity: adapter.identity, key: idempotencyKey, op, signal: context.signal });
+  if (claim.outcome === "existing") return existingMutationResult(claim.record);
+
+  let result: { draftId: string; revision: number; resourceId?: string };
+  try {
+    const markAppRes = adapter.markDraft(draft.draftId, "approved");
+    draft = markAppRes instanceof Promise ? await markAppRes : markAppRes;
+    const value = await adapter.runOp(op as never, draft.payload, context.signal);
+    const markExecRes = adapter.markDraft(draft.draftId, "executed");
+    draft = markExecRes instanceof Promise ? await markExecRes : markExecRes;
+    result = {
+      draftId: draft.draftId,
+      revision: draft.revision,
+      ...(typeof (value as { id?: string })?.id === "string" ? { resourceId: (value as { id: string }).id } : {}),
+    };
+  } catch (error) {
+    if (claim.record.claimToken) {
+      const input = {
+        identity: adapter.identity,
+        key: idempotencyKey,
+        op,
+        claimToken: claim.record.claimToken,
+        expectedVersion: claim.record.version,
+      };
+      const failure = classifiedFailure(error);
+      if (failure) {
+        await store.fail({ ...input, ...failure });
+      } else {
+        await store.markUnknown({ ...input, failure: { code: "ERR_PRISM_WORK_IDEMPOTENCY_UNKNOWN" } });
+        try {
+          const markUnkRes = adapter.markDraft(draft.draftId, "unknown");
+          if (markUnkRes instanceof Promise) await markUnkRes;
+        } catch {
+          // ignore draft mark error
+        }
+      }
+    }
+    throw error;
+  }
+  if (claim.record.claimToken) {
+    await store.complete({
+      identity: adapter.identity,
+      key: idempotencyKey!,
+      op,
+      claimToken: claim.record.claimToken,
+      expectedVersion: claim.record.version,
+      result: {
+        draftId: result.draftId,
+        ...(result.resourceId ? { resourceId: result.resourceId } : {}),
+      },
+    });
+  }
+  return { ...result, status: "executed", untrusted: true as const };
+}
+
+function existingMutationResult(record: WorkMutationRecord): {
+  readonly draftId: string;
+  readonly resourceId?: string;
+  readonly status: "duplicate";
+  readonly untrusted: true;
+} {
+  if (record.status === "completed" && record.result) {
+    return { ...record.result, status: "duplicate", untrusted: true };
+  }
+  if (record.status === "unknown") {
+    throw new WorkToolError("ERR_PRISM_WORK_IDEMPOTENCY_UNKNOWN", "mutation outcome requires reconciliation");
+  }
+  throw new WorkToolError("ERR_PRISM_WORK_IDEMPOTENCY", "mutation is not available for replay");
+}
+
+function classifiedFailure(
+  error: unknown,
+): { readonly status: "failed_retryable" | "failed_terminal"; readonly failure: { readonly code: string } } | undefined {
+  if (!(error instanceof WorkToolError)) return undefined;
+  if (error.code === "ERR_PRISM_WORK_CREDENTIAL") return { status: "failed_retryable", failure: { code: error.code } };
+  if (error.code === "ERR_PRISM_WORK_INPUT" || error.code === "ERR_PRISM_WORK_POLICY" || error.code === "ERR_PRISM_WORK_LIMIT") {
+    return { status: "failed_terminal", failure: { code: error.code } };
+  }
+  return undefined;
+}
+
+export function pushTool(tools: ToolDefinition[], tool: ToolDefinition): void {
+  tools.push(tool);
+}

package/work/src/connectors/tools.ts

@@ -0,0 +1,42 @@
+import { type ToolDefinition, type ToolEffectDeclaration } from "@arnilo/prism";
+import { pushGwsTools } from "./gws-tools.js";
+import { pushM365Tools } from "./m365-tools.js";
+import type { WorkToolsOptions } from "./types.js";
+
+const WORK_OBSERVATION_EFFECT = { kind: "none", idempotency: "none" } as const satisfies ToolEffectDeclaration;
+const WORK_MUTATION_EFFECT = { kind: "external_mutation", idempotency: "tool_managed" } as const satisfies ToolEffectDeclaration;
+const NETWORK_EFFECTS = ["network"] as const;
+const NETWORK_EXTERNAL_EFFECTS = ["network", "external"] as const;
+/** Connector writes; the rest of the group only reads. Exported so the package can assert coverage. */
+export const WORK_MUTATING_TOOL_NAMES: ReadonlySet<string> = new Set([
+  "m365_mail_draft_send",
+  "m365_calendar_draft_add",
+  "m365_file_draft_upload",
+  "m365_file_draft_copy",
+  "m365_file_draft_share",
+  "m365_todo_draft_add",
+  "m365_todo_draft_complete",
+  "gws_mail_draft_send",
+  "gws_calendar_draft_add",
+  "gws_file_draft_upload",
+  "gws_file_draft_share",
+  "gws_task_draft_add",
+  "gws_task_draft_complete",
+  "gws_docs_draft_create",
+  "gws_docs_draft_update",
+  "gws_sheets_draft_create",
+  "gws_sheets_draft_update",
+  "gws_slides_draft_create",
+  "gws_slides_draft_update",
+]);
+
+export function createWorkTools(options: WorkToolsOptions): readonly ToolDefinition[] {
+  const tools: ToolDefinition[] = [];
+  if (options.microsoft365) pushM365Tools(tools, options, options.microsoft365);
+  if (options.googleWorkspace) pushGwsTools(tools, options, options.googleWorkspace);
+  return tools.map((tool) => ({
+    ...tool,
+    effect: WORK_MUTATING_TOOL_NAMES.has(tool.name) ? WORK_MUTATION_EFFECT : WORK_OBSERVATION_EFFECT,
+    effects: WORK_MUTATING_TOOL_NAMES.has(tool.name) ? NETWORK_EXTERNAL_EFFECTS : NETWORK_EFFECTS,
+  }));
+}