@anthusai/papyrus 0.0.0 → 1.0.0-next.1

package/amplify/functions/console-chat-responder/Cargo.toml

@@ -0,0 +1,26 @@
+[package]
+name = "papyrus_console_chat_responder"
+version = "0.1.0"
+edition = "2024"
+
+[dependencies]
+anyhow = "1.0.102"
+aws-config = "1.8.17"
+aws-credential-types = "1.2.14"
+aws-sdk-dynamodb = "1.112.0"
+aws-sdk-ssm = "1.110.0"
+aws-sigv4 = { version = "1.4.4", features = ["http1"] }
+aws_lambda_events = "1.2.0"
+base64 = "0.22.1"
+chrono = { version = "0.4.44", features = ["serde"] }
+futures-util = "0.3.31"
+http = "1.4.0"
+lambda_runtime = "1.2.0"
+reqwest = { version = "0.13.3", features = ["json", "stream"] }
+serde = { version = "1.0.228", features = ["derive"] }
+serde_json = "1.0.150"
+sha2 = "0.11.0"
+tokio = { version = "1.52.3", features = ["macros", "rt-multi-thread", "io-util", "process", "time"] }
+tracing = "0.1.44"
+tracing-subscriber = "0.3.23"
+uuid = { version = "1.23.1", features = ["v4"] }

package/amplify/functions/console-chat-responder/Dockerfile

@@ -0,0 +1,19 @@
+FROM rust:1.91.1-bookworm AS build
+WORKDIR /workspace/amplify/functions/console-chat-responder
+
+COPY amplify/functions/console-chat-responder/Cargo.toml amplify/functions/console-chat-responder/Cargo.lock ./
+COPY amplify/functions/console-chat-responder/src ./src
+RUN cargo build --release
+
+FROM public.ecr.aws/lambda/provided:al2023
+COPY --from=build /workspace/amplify/functions/console-chat-responder/target/release/papyrus_console_chat_responder /var/runtime/bootstrap
+RUN dnf --setopt=cachedir=/tmp/dnf-cache install -y python3 python3-pip \
+    && python3 -m pip install --no-cache-dir PyYAML botocore tiktoken \
+    && python3 -m pip install --no-cache-dir tactus==0.44.1 \
+    && dnf clean all \
+    && rm -rf /tmp/dnf-cache /var/cache/dnf /var/cache/yum
+COPY src /opt/papyrus/src
+COPY amplify/functions/console-chat-responder/py/execute_tactus_runner.py /opt/papyrus/execute_tactus_runner.py
+ENV PYTHONPATH=/opt/papyrus/src
+RUN chmod +x /var/runtime/bootstrap
+CMD ["/var/runtime/bootstrap"]

package/amplify/functions/console-chat-responder/py/execute_tactus_runner.py

@@ -0,0 +1,116 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Any
+
+SEARCH_PATHS = [
+    Path("/opt/papyrus/src"),
+    Path.cwd() / "src",
+]
+for root in SEARCH_PATHS:
+    if root.exists() and str(root) not in sys.path:
+        sys.path.insert(0, str(root))
+
+
+def _ensure_graphql_authoring_jwt() -> None:
+    if not os.environ.get("AWS_LAMBDA_FUNCTION_NAME", "").strip():
+        return
+    from papyrus_content.env import ensure_graphql_authoring_jwt  # type: ignore
+
+    ensure_graphql_authoring_jwt()
+
+
+def _error(code: str, message: str, *, retryable: bool = False) -> dict[str, Any]:
+    return {
+        "ok": False,
+        "error": {
+            "code": code,
+            "message": message,
+            "retryable": retryable,
+        },
+    }
+
+
+def _docs_index() -> dict[str, Any]:
+    try:
+        from papyrus_newsroom.tactus_runtime import DOCS  # type: ignore
+    except Exception as exc:
+        return _error("runner_unavailable", f"Unable to import papyrus_newsroom.tactus_runtime: {exc}")
+
+    entries: list[dict[str, str]] = []
+    for doc in DOCS.values():
+        entries.append(
+            {
+                "id": str(doc.get("id") or ""),
+                "title": str(doc.get("title") or ""),
+                "summary": str(doc.get("summary") or ""),
+                "namespace": str(doc.get("namespace") or ""),
+            }
+        )
+    entries.sort(key=lambda entry: entry["id"])
+    return {"entries": entries}
+
+
+def _coerce_web_ui_context(payload: Any) -> dict[str, Any] | None:
+    if not isinstance(payload, dict):
+        return None
+    web_path = str(payload.get("webPath") or payload.get("web_path") or "").strip()
+    papyrus_location_uri = str(
+        payload.get("papyrusLocationUri") or payload.get("papyrus_location_uri") or ""
+    ).strip()
+    if not web_path and not papyrus_location_uri:
+        return None
+    context = dict(payload)
+    if web_path:
+        context["webPath"] = web_path
+    if papyrus_location_uri:
+        context["papyrusLocationUri"] = papyrus_location_uri
+    return context
+
+
+def _execute_tactus(arguments: dict[str, Any], web_ui_context: dict[str, Any] | None = None) -> dict[str, Any]:
+    try:
+        from papyrus_newsroom.tactus_runtime import execute_tactus_harnessed  # type: ignore
+    except Exception as exc:
+        return _error("runner_unavailable", f"Unable to import papyrus_newsroom.tactus_runtime: {exc}")
+
+    try:
+        return execute_tactus_harnessed(
+            str(arguments.get("tactus") or ""),
+            harness=str(arguments.get("harness") or "raw"),
+            assignment_id=str(arguments.get("assignment_id") or arguments.get("assignmentId") or ""),
+            assignment_item_json=str(arguments.get("assignment_item_json") or arguments.get("assignmentItemJson") or ""),
+            corpus_key=str(arguments.get("corpus_key") or arguments.get("corpusKey") or ""),
+            max_evidence_items=int(arguments.get("max_evidence_items") or arguments.get("maxEvidenceItems") or 20),
+            research_mode=str(arguments.get("research_mode") or arguments.get("researchMode") or ""),
+            web_ui_context=web_ui_context,
+        )
+    except Exception as exc:
+        return _error("tactus_execution_failed", f"Unexpected error: {exc}")
+
+
+def main() -> None:
+    _ensure_graphql_authoring_jwt()
+    raw = sys.stdin.read()
+    payload = json.loads(raw or "{}")
+    mode = str(payload.get("mode") or "").strip()
+
+    if mode == "docs_index":
+        print(json.dumps(_docs_index()))
+        return
+
+    if mode == "execute_tactus":
+        args = payload.get("arguments") if isinstance(payload.get("arguments"), dict) else {}
+        web_ui_context = _coerce_web_ui_context(payload.get("webUi") or payload.get("web_ui"))
+        print(json.dumps(_execute_tactus(args, web_ui_context=web_ui_context)))
+        return
+
+    print(json.dumps(_error("invalid_mode", f"Unsupported mode: {mode}")))
+
+
+if __name__ == "__main__":
+    main()

package/amplify/functions/console-chat-responder/resource.js

@@ -0,0 +1,153 @@
+import { Duration, NestedStack, Stack } from "aws-cdk-lib";
+import { Platform } from "aws-cdk-lib/aws-ecr-assets";
+import { Repository } from "aws-cdk-lib/aws-ecr";
+import { Effect, PolicyStatement } from "aws-cdk-lib/aws-iam";
+import { Architecture, CfnEventSourceMapping, DockerImageCode, DockerImageFunction } from "aws-cdk-lib/aws-lambda";
+export class ConsoleChatResponderStack extends NestedStack {
+    responderFunction;
+    constructor(scope, id, props) {
+        super(scope, id, props);
+        const responseTarget = props.responseTarget?.trim() || "cloud";
+        const environment = {
+            PAPYRUS_MESSAGE_TABLE_NAME: props.messageTable.tableName,
+            PAPYRUS_MESSAGE_THREAD_TABLE_NAME: props.threadTable.tableName,
+            PAPYRUS_MESSAGE_THREAD_SEQUENCE_INDEX_NAME: "messagesByThreadSequence",
+            PAPYRUS_GRAPHQL_ENDPOINT: props.graphqlEndpoint,
+            PAPYRUS_CONSOLE_RESPONSE_TARGET: responseTarget,
+            PAPYRUS_CONSOLE_MODEL: props.model?.trim() || process.env.PAPYRUS_CONSOLE_MODEL || "gpt-5-nano",
+            PAPYRUS_CONSOLE_CONTEXT_CACHE_ROOT: "/tmp/papyrus-console/thread-context",
+            PAPYRUS_CONSOLE_STATIC_CONTEXT_TTL_SECONDS: process.env.PAPYRUS_CONSOLE_STATIC_CONTEXT_TTL_SECONDS || "900",
+            PAPYRUS_EXECUTE_TACTUS_RUNNER: process.env.PAPYRUS_EXECUTE_TACTUS_RUNNER || "/opt/papyrus/execute_tactus_runner.py",
+            PAPYRUS_EXECUTE_TACTUS_TIMEOUT_SECONDS: process.env.PAPYRUS_EXECUTE_TACTUS_TIMEOUT_SECONDS || "30",
+            PAPYRUS_JWT_ISSUER: process.env.PAPYRUS_JWT_ISSUER || "papyrus-cli",
+            PAPYRUS_JWT_SUBJECT: process.env.PAPYRUS_JWT_SUBJECT || "papyrus-cli",
+            PAPYRUS_JWT_AUDIENCE: process.env.PAPYRUS_JWT_AUDIENCE || "papyrus-authoring",
+            PAPYRUS_JWT_GROUPS: process.env.PAPYRUS_JWT_GROUPS || "editor",
+            ...(props.amplifySsmEnvConfig ? { AMPLIFY_SSM_ENV_CONFIG: props.amplifySsmEnvConfig } : {}),
+        };
+        const imageUri = props.prebuiltImageUri?.trim() || process.env.PAPYRUS_CONSOLE_RESPONDER_IMAGE_URI?.trim() || "";
+        const allowLocalImageBuild = parseBooleanEnv(process.env.PAPYRUS_CONSOLE_RESPONDER_ALLOW_LOCAL_BUILD);
+        let code;
+        if (imageUri) {
+            const { repositoryName, tagOrDigest } = parseEcrImageUri(imageUri);
+            assertArm64ImageUri(imageUri, tagOrDigest);
+            const repository = Repository.fromRepositoryName(this, "ConsoleChatResponderRepository", repositoryName);
+            code = DockerImageCode.fromEcr(repository, { tagOrDigest });
+        }
+        else {
+            if (!allowLocalImageBuild) {
+                throw new Error("ConsoleChatResponder requires PAPYRUS_CONSOLE_RESPONDER_IMAGE_URI (prebuilt ECR image). "
+                    + "Set PAPYRUS_CONSOLE_RESPONDER_ALLOW_LOCAL_BUILD=true only when intentionally using local Docker image builds.");
+            }
+            code = DockerImageCode.fromImageAsset(props.projectRoot, {
+                file: "amplify/functions/console-chat-responder/Dockerfile",
+                platform: Platform.LINUX_ARM64,
+                exclude: [
+                    ".git",
+                    ".env",
+                    ".env.*",
+                    ".next",
+                    ".amplify",
+                    "node_modules",
+                    "coverage",
+                    "dist",
+                    "out",
+                    "corpora",
+                    ".papyrus-runs",
+                    "amplify_outputs.json",
+                    "amplify_outputs.json.*",
+                    "amplify/functions/console-chat-responder/target",
+                ],
+            });
+        }
+        this.responderFunction = new DockerImageFunction(this, "ConsoleChatResponderFunction", {
+            code,
+            architecture: Architecture.ARM_64,
+            timeout: Duration.minutes(2),
+            memorySize: 1024,
+            environment,
+            description: "Rust responder for Papyrus editor console chat Message stream",
+        });
+        new CfnEventSourceMapping(this, "ConsoleResponderMessageStreamMapping", {
+            batchSize: 1,
+            eventSourceArn: props.messageStreamArn,
+            functionName: this.responderFunction.functionArn,
+            functionResponseTypes: ["ReportBatchItemFailures"],
+            maximumRetryAttempts: 2,
+            startingPosition: "LATEST",
+        });
+        props.messageTable.grantReadWriteData(this.responderFunction);
+        props.threadTable.grantReadWriteData(this.responderFunction);
+        this.responderFunction.addToRolePolicy(new PolicyStatement({
+            effect: Effect.ALLOW,
+            actions: ["dynamodb:Query"],
+            resources: [
+                `${props.messageTable.tableArn}/index/*`,
+                `${props.threadTable.tableArn}/index/*`,
+            ],
+        }));
+        const stack = Stack.of(this);
+        // execute_tactus_runner mints PAPYRUS_GRAPHQL_JWT via boto3 get_parameters; branch policies
+        // often grant GetParameters on path prefixes, not GetParameter per secret name.
+        this.responderFunction.addToRolePolicy(new PolicyStatement({
+            effect: Effect.ALLOW,
+            actions: ["ssm:GetParameter", "ssm:GetParameters"],
+            resources: [
+                `arn:aws:ssm:${stack.region}:${stack.account}:parameter/amplify/papyrus/*`,
+                `arn:aws:ssm:${stack.region}:${stack.account}:parameter/amplify/shared/papyrus/*`,
+                `arn:aws:ssm:${stack.region}:${stack.account}:parameter/amplify/shared/*`,
+                `arn:aws:ssm:${stack.region}:${stack.account}:parameter/amplify/dbsyytcm9drqa/*`,
+                `arn:aws:ssm:${stack.region}:${stack.account}:parameter/amplify/shared/dbsyytcm9drqa/*`,
+            ],
+        }));
+        this.responderFunction.addToRolePolicy(new PolicyStatement({
+            effect: Effect.ALLOW,
+            actions: ["appsync:GraphQL"],
+            resources: ["*"],
+        }));
+        this.responderFunction.addToRolePolicy(new PolicyStatement({
+            effect: Effect.ALLOW,
+            actions: [
+                "dynamodb:DescribeStream",
+                "dynamodb:GetRecords",
+                "dynamodb:GetShardIterator",
+                "dynamodb:ListStreams",
+            ],
+            resources: [props.messageStreamArn],
+        }));
+    }
+}
+function parseBooleanEnv(value) {
+    if (!value)
+        return false;
+    return ["1", "true", "yes", "on"].includes(value.trim().toLowerCase());
+}
+function parseEcrImageUri(imageUri) {
+    const trimmed = imageUri.trim();
+    const hostAndPath = trimmed.split("/");
+    if (hostAndPath.length < 2) {
+        throw new Error(`Invalid PAPYRUS_CONSOLE_RESPONDER_IMAGE_URI: ${trimmed}`);
+    }
+    const imagePath = hostAndPath.slice(1).join("/");
+    if (imagePath.includes("@sha256:")) {
+        const [repositoryName, digest] = imagePath.split("@", 2);
+        if (!repositoryName || !digest) {
+            throw new Error(`Invalid PAPYRUS_CONSOLE_RESPONDER_IMAGE_URI digest form: ${trimmed}`);
+        }
+        return { repositoryName, tagOrDigest: digest };
+    }
+    const colonIndex = imagePath.lastIndexOf(":");
+    if (colonIndex <= 0 || colonIndex === imagePath.length - 1) {
+        throw new Error(`PAPYRUS_CONSOLE_RESPONDER_IMAGE_URI must include a tag (repo:tag) or digest: ${trimmed}`);
+    }
+    return {
+        repositoryName: imagePath.slice(0, colonIndex),
+        tagOrDigest: imagePath.slice(colonIndex + 1),
+    };
+}
+function assertArm64ImageUri(imageUri, tagOrDigest) {
+    const normalized = `${imageUri} ${tagOrDigest}`.toLowerCase();
+    if (normalized.includes("amd64") || normalized.includes("x86_64")) {
+        throw new Error(`PAPYRUS_CONSOLE_RESPONDER_IMAGE_URI must reference an ARM64 image, but received: ${imageUri}`);
+    }
+}

package/amplify/functions/console-chat-responder/resource.ts

@@ -0,0 +1,179 @@
+import { Duration, NestedStack, Stack, type NestedStackProps } from "aws-cdk-lib";
+import { Platform } from "aws-cdk-lib/aws-ecr-assets";
+import { Repository } from "aws-cdk-lib/aws-ecr";
+import { Effect, PolicyStatement } from "aws-cdk-lib/aws-iam";
+import { Architecture, CfnEventSourceMapping, DockerImageCode, DockerImageFunction } from "aws-cdk-lib/aws-lambda";
+import type { ITable } from "aws-cdk-lib/aws-dynamodb";
+import { Construct } from "constructs";
+
+export type ConsoleChatResponderStackProps = NestedStackProps & {
+  messageTable: ITable;
+  messageStreamArn: string;
+  threadTable: ITable;
+  projectRoot: string;
+  graphqlEndpoint: string;
+  amplifySsmEnvConfig?: string;
+  responseTarget?: string;
+  model?: string;
+  prebuiltImageUri?: string;
+};
+
+export class ConsoleChatResponderStack extends NestedStack {
+  public readonly responderFunction: DockerImageFunction;
+
+  constructor(scope: Construct, id: string, props: ConsoleChatResponderStackProps) {
+    super(scope, id, props);
+
+    const responseTarget = props.responseTarget?.trim() || "cloud";
+    const environment: Record<string, string> = {
+      PAPYRUS_MESSAGE_TABLE_NAME: props.messageTable.tableName,
+      PAPYRUS_MESSAGE_THREAD_TABLE_NAME: props.threadTable.tableName,
+      PAPYRUS_MESSAGE_THREAD_SEQUENCE_INDEX_NAME: "messagesByThreadSequence",
+      PAPYRUS_GRAPHQL_ENDPOINT: props.graphqlEndpoint,
+      PAPYRUS_CONSOLE_RESPONSE_TARGET: responseTarget,
+      PAPYRUS_CONSOLE_MODEL: props.model?.trim() || process.env.PAPYRUS_CONSOLE_MODEL || "gpt-5-nano",
+      PAPYRUS_CONSOLE_CONTEXT_CACHE_ROOT: "/tmp/papyrus-console/thread-context",
+      PAPYRUS_CONSOLE_STATIC_CONTEXT_TTL_SECONDS: process.env.PAPYRUS_CONSOLE_STATIC_CONTEXT_TTL_SECONDS || "900",
+      PAPYRUS_EXECUTE_TACTUS_RUNNER: process.env.PAPYRUS_EXECUTE_TACTUS_RUNNER || "/opt/papyrus/execute_tactus_runner.py",
+      PAPYRUS_EXECUTE_TACTUS_TIMEOUT_SECONDS: process.env.PAPYRUS_EXECUTE_TACTUS_TIMEOUT_SECONDS || "30",
+      PAPYRUS_JWT_ISSUER: process.env.PAPYRUS_JWT_ISSUER || "papyrus-cli",
+      PAPYRUS_JWT_SUBJECT: process.env.PAPYRUS_JWT_SUBJECT || "papyrus-cli",
+      PAPYRUS_JWT_AUDIENCE: process.env.PAPYRUS_JWT_AUDIENCE || "papyrus-authoring",
+      PAPYRUS_JWT_GROUPS: process.env.PAPYRUS_JWT_GROUPS || "editor",
+      ...(props.amplifySsmEnvConfig ? { AMPLIFY_SSM_ENV_CONFIG: props.amplifySsmEnvConfig } : {}),
+    };
+
+    const imageUri = props.prebuiltImageUri?.trim() || process.env.PAPYRUS_CONSOLE_RESPONDER_IMAGE_URI?.trim() || "";
+    const allowLocalImageBuild = parseBooleanEnv(process.env.PAPYRUS_CONSOLE_RESPONDER_ALLOW_LOCAL_BUILD);
+    let code: DockerImageCode;
+    if (imageUri) {
+      const { repositoryName, tagOrDigest } = parseEcrImageUri(imageUri);
+      assertArm64ImageUri(imageUri, tagOrDigest);
+      const repository = Repository.fromRepositoryName(this, "ConsoleChatResponderRepository", repositoryName);
+      code = DockerImageCode.fromEcr(repository, { tagOrDigest });
+    } else {
+      if (!allowLocalImageBuild) {
+        throw new Error(
+          "ConsoleChatResponder requires PAPYRUS_CONSOLE_RESPONDER_IMAGE_URI (prebuilt ECR image). "
+          + "Set PAPYRUS_CONSOLE_RESPONDER_ALLOW_LOCAL_BUILD=true only when intentionally using local Docker image builds.",
+        );
+      }
+      code = DockerImageCode.fromImageAsset(props.projectRoot, {
+        file: "amplify/functions/console-chat-responder/Dockerfile",
+        platform: Platform.LINUX_ARM64,
+        exclude: [
+          ".git",
+          ".env",
+          ".env.*",
+          ".next",
+          ".amplify",
+          "node_modules",
+          "coverage",
+          "dist",
+          "out",
+          "corpora",
+          ".papyrus-runs",
+          "amplify_outputs.json",
+          "amplify_outputs.json.*",
+          "amplify/functions/console-chat-responder/target",
+        ],
+      });
+    }
+
+    this.responderFunction = new DockerImageFunction(this, "ConsoleChatResponderFunction", {
+      code,
+      architecture: Architecture.ARM_64,
+      timeout: Duration.minutes(2),
+      memorySize: 1024,
+      environment,
+      description: "Rust responder for Papyrus editor console chat Message stream",
+    });
+
+    new CfnEventSourceMapping(this, "ConsoleResponderMessageStreamMapping", {
+      batchSize: 1,
+      eventSourceArn: props.messageStreamArn,
+      functionName: this.responderFunction.functionArn,
+      functionResponseTypes: ["ReportBatchItemFailures"],
+      maximumRetryAttempts: 2,
+      startingPosition: "LATEST",
+    });
+
+    props.messageTable.grantReadWriteData(this.responderFunction);
+    props.threadTable.grantReadWriteData(this.responderFunction);
+    this.responderFunction.addToRolePolicy(new PolicyStatement({
+      effect: Effect.ALLOW,
+      actions: ["dynamodb:Query"],
+      resources: [
+        `${props.messageTable.tableArn}/index/*`,
+        `${props.threadTable.tableArn}/index/*`,
+      ],
+    }));
+    const stack = Stack.of(this);
+    // execute_tactus_runner mints PAPYRUS_GRAPHQL_JWT via boto3 get_parameters; branch policies
+    // often grant GetParameters on path prefixes, not GetParameter per secret name.
+    this.responderFunction.addToRolePolicy(new PolicyStatement({
+      effect: Effect.ALLOW,
+      actions: ["ssm:GetParameter", "ssm:GetParameters"],
+      resources: [
+        `arn:aws:ssm:${stack.region}:${stack.account}:parameter/amplify/papyrus/*`,
+        `arn:aws:ssm:${stack.region}:${stack.account}:parameter/amplify/shared/papyrus/*`,
+        `arn:aws:ssm:${stack.region}:${stack.account}:parameter/amplify/shared/*`,
+        `arn:aws:ssm:${stack.region}:${stack.account}:parameter/amplify/dbsyytcm9drqa/*`,
+        `arn:aws:ssm:${stack.region}:${stack.account}:parameter/amplify/shared/dbsyytcm9drqa/*`,
+      ],
+    }));
+    this.responderFunction.addToRolePolicy(new PolicyStatement({
+      effect: Effect.ALLOW,
+      actions: ["appsync:GraphQL"],
+      resources: ["*"],
+    }));
+    this.responderFunction.addToRolePolicy(new PolicyStatement({
+      effect: Effect.ALLOW,
+      actions: [
+        "dynamodb:DescribeStream",
+        "dynamodb:GetRecords",
+        "dynamodb:GetShardIterator",
+        "dynamodb:ListStreams",
+      ],
+      resources: [props.messageStreamArn],
+    }));
+  }
+}
+
+function parseBooleanEnv(value: string | undefined): boolean {
+  if (!value) return false;
+  return ["1", "true", "yes", "on"].includes(value.trim().toLowerCase());
+}
+
+function parseEcrImageUri(imageUri: string): { repositoryName: string; tagOrDigest: string } {
+  const trimmed = imageUri.trim();
+  const hostAndPath = trimmed.split("/");
+  if (hostAndPath.length < 2) {
+    throw new Error(`Invalid PAPYRUS_CONSOLE_RESPONDER_IMAGE_URI: ${trimmed}`);
+  }
+  const imagePath = hostAndPath.slice(1).join("/");
+  if (imagePath.includes("@sha256:")) {
+    const [repositoryName, digest] = imagePath.split("@", 2);
+    if (!repositoryName || !digest) {
+      throw new Error(`Invalid PAPYRUS_CONSOLE_RESPONDER_IMAGE_URI digest form: ${trimmed}`);
+    }
+    return { repositoryName, tagOrDigest: digest };
+  }
+  const colonIndex = imagePath.lastIndexOf(":");
+  if (colonIndex <= 0 || colonIndex === imagePath.length - 1) {
+    throw new Error(`PAPYRUS_CONSOLE_RESPONDER_IMAGE_URI must include a tag (repo:tag) or digest: ${trimmed}`);
+  }
+  return {
+    repositoryName: imagePath.slice(0, colonIndex),
+    tagOrDigest: imagePath.slice(colonIndex + 1),
+  };
+}
+
+function assertArm64ImageUri(imageUri: string, tagOrDigest: string): void {
+  const normalized = `${imageUri} ${tagOrDigest}`.toLowerCase();
+  if (normalized.includes("amd64") || normalized.includes("x86_64")) {
+    throw new Error(
+      `PAPYRUS_CONSOLE_RESPONDER_IMAGE_URI must reference an ARM64 image, but received: ${imageUri}`,
+    );
+  }
+}