elan-agentkit-core 0.1.0__py3-none-any.whl

agentkit_core/__init__.py

@@ -0,0 +1,85 @@
+"""Shared contracts for the agent pipeline."""
+
+from agentkit_core.autonomy import (
+    ANY_TOOL,
+    ANY_USER,
+    Decision,
+    StoredPolicy,
+    fingerprint,
+    resolve,
+    stored_shape,
+)
+from agentkit_core.context import (
+    bind_invocation,
+    current_invocation,
+    current_segment,
+    drain_signals,
+    emit_signal,
+)
+from agentkit_core.envelopes import (
+    AgentEventEnvelope,
+    InvocationEnvelope,
+    MessagePart,
+    ResumeEnvelope,
+    new_id,
+)
+from agentkit_core.errors import (
+    AgentkitError,
+    BadEnvelopeError,
+    InsufficientFundsError,
+    ManifestError,
+    SaturatedError,
+)
+from agentkit_core.manifest import (
+    SLUG_PATTERN,
+    ActionPolicy,
+    AgentManifest,
+    BaseTargetManifest,
+    Billing,
+    Limits,
+    NodeOverrides,
+    Rule,
+    TargetManifest,
+    Tier,
+    ToolBinding,
+    ToolPhrasing,
+    WorkflowManifest,
+)
+
+__all__ = [
+    "ANY_TOOL",
+    "ANY_USER",
+    "SLUG_PATTERN",
+    "ActionPolicy",
+    "AgentEventEnvelope",
+    "AgentManifest",
+    "AgentkitError",
+    "BadEnvelopeError",
+    "BaseTargetManifest",
+    "Billing",
+    "Decision",
+    "InsufficientFundsError",
+    "InvocationEnvelope",
+    "Limits",
+    "ManifestError",
+    "MessagePart",
+    "NodeOverrides",
+    "ResumeEnvelope",
+    "Rule",
+    "SaturatedError",
+    "StoredPolicy",
+    "Tier",
+    "bind_invocation",
+    "current_invocation",
+    "current_segment",
+    "drain_signals",
+    "emit_signal",
+    "fingerprint",
+    "TargetManifest",
+    "ToolBinding",
+    "ToolPhrasing",
+    "WorkflowManifest",
+    "new_id",
+    "resolve",
+    "stored_shape",
+]

agentkit_core/approvals.py

@@ -0,0 +1,364 @@
+"""An approval a developer declares: who answers it, what they fill in, and
+what happens when they do (ADR-0144).
+
+WHY THIS IS NOT A CONFIRMATION, which is the whole design. ADK resolves every
+outstanding confirmation with the NEXT USER MESSAGE. That is harmless when the
+person deciding is the person typing — they click, and carry on. It is fatal
+when the decider is somebody else: the request sits there while the end user,
+who cannot answer it, sends the message that throws it away. Measured on a real
+conversation, where "ok" cancelled a refund the manager approved three minutes
+later.
+
+A LONG-RUNNING CALL SURVIVES THAT, and is the mechanism here. `is_long_running`
+makes ADK record the call id and skip building an automatic response, so the
+turn pauses on a call nothing will resolve until somebody answers it — however
+much the conversation moves on meanwhile.
+
+WHAT A CONFIRMATION GAVE FOR FREE AND THIS HAS TO SUPPLY. A confirmation
+RE-RUNS its tool body with `confirmed=True`, so the tool does the work itself. A
+long-running tool does not re-run: its result is injected as the function
+response and the model reads it. So the work goes in `on_approval` / `on_deny`,
+which the platform invokes when the decision arrives and whose return value
+becomes the tool's return value. No model discipline, and no tool call
+synthesised that ADK never asked for.
+
+READ THE CONSTRAINT ON A CALLBACK BEFORE WRITING ONE: `ApprovalRequest` says
+what it gets and `on_approval`'s own docstring says what it cannot reach.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any, Literal
+
+from agentkit_core.manifest import WorkflowInput
+
+logger = logging.getLogger(__name__)
+
+#: One field on an approval's form.
+#:
+#: THE SAME MODEL A WORKFLOW'S LAUNCH FORM USES, aliased rather than copied.
+#: It already carries the seven types, enum options, a default, requiredness,
+#: help text and the validators — and this repo's rule for that list is to
+#: write it once, so one renderer serves both and neither can drift from it.
+ApprovalField = WorkflowInput
+
+#: Who is expected to answer.
+#:
+#: `admin` is somebody holding the tenant's admin role; `end_user` is the person
+#: the run belongs to, answered through whatever product that run came from.
+#: Named for the check performed rather than for the organisation it stands
+#: for — there is no separate approver role on this platform.
+Asks = Literal["admin", "end_user"]
+
+#: The `status` on the INITIAL result ADK hands straight back to the model.
+#:
+#: A MARKER AS WELL AS A WORD. The engine's redelivery guard asks "has this
+#: call been answered already", and under ADK's long-running contract the
+#: answer is always yes — the initial result IS a `FunctionResponse` against
+#: the same id. So the guard tells the two apart by this value, which is why
+#: a tool's own `pending` fields cannot overwrite it.
+AWAITING = "awaiting_approval"
+
+
+@dataclass(frozen=True, slots=True)
+class ApprovalRequest:
+    """Everything a callback is given, and the only thing it is given.
+
+    ONE OBJECT RATHER THAN A SIGNATURE, so adding a fact later does not break
+    every callback anybody has written.
+    """
+
+    call_id: str
+    tool: str
+    approved: bool
+    answers: dict[str, Any]
+    """What the approver filled in, coerced against the declared fields."""
+
+    decided_by: str
+    note: str
+    tool_args: dict[str, Any]
+    """What the model called the tool with, which is what was approved."""
+
+    state: dict[str, Any]
+    """The conversation's session state, read when the decision is applied.
+
+    THE ONLY WAY A CALLBACK SEES STATE, and it is read BY THE ENGINE rather
+    than by the callback: `ToolContext.state` belongs to an invocation context,
+    and none exists out here. The engine already loads the session to check
+    this decision is not a redelivery, so it hands over what it read.
+
+    READ-ONLY, AND A SNAPSHOT. Writing to it does nothing — ADK applies state
+    through an event's delta and there is no event here. If the work needs to
+    be recorded in the conversation, return it: the return value becomes the
+    tool's result and the model sees it.
+
+    AT DECISION TIME, NOT AT REQUEST TIME. An earlier design captured it in the
+    tool body and could not work at all: ADK yields the model-response event —
+    which is where the pause is detected and the request filed — BEFORE it runs
+    the body, so anything captured there was always too late.
+    """
+
+    invocation_id: str
+    session_id: str
+    tenant_id: str
+    project_id: str
+    user_id: str
+    target_slug: str
+
+
+@dataclass(frozen=True, slots=True)
+class ApprovalContext:
+    """What `describe` is given, when the request is being filed.
+
+    ONE OBJECT, like `ApprovalRequest`, so adding a fact later does not break
+    every `describe` anybody has written.
+    """
+
+    tool: str
+    tool_args: dict[str, Any]
+    """What the model called the tool with."""
+
+    state: dict[str, Any]
+    """The conversation's session state, read by the engine as it files this.
+
+    THE ANSWER TO "WHAT AM I APPROVING", and it has to come from here rather
+    than from the model. The arguments on a card are the model's account of
+    what it wants; this is the record itself. An approver shown a count the
+    model asserted is approving the assertion, not the thing.
+
+    IT IS READ BEFORE THE TOOL BODY RUNS, which is why this is a property of
+    the ENGINE and not something a tool can do for itself: ADK files the
+    request first and calls the body afterwards.
+    """
+
+
+class ApprovalTool:
+    """A tool whose call files an approval and waits for somebody to answer it.
+
+    NAMED WITHOUT THE BRAND, DELIBERATELY. These packages are `agentkit_*` and
+    carry no project-specific value — this repo is also the starter template
+    for other platforms, and `tests/test_template.py` enforces it by scanning
+    source. A product that wants its own name on this aliases it in its SDK,
+    which is where the brand already lives.
+
+    Built on `BaseTool` with `is_long_running=True` and NOTHING ELSE, which is
+    worth saying because the obvious base classes are both wrong:
+
+    `LongRunningFunctionTool`/`FunctionTool` derive the name from a callable and
+    — the part that matters — their `run_async` returns a TRUTHY error dict when
+    the model omits an argument. ADK then builds a response while the id is
+    already marked long-running, so a model's typo would file an approval nobody
+    could ever clear.
+
+    `_defers_response` has the same skip-on-empty behaviour but does NOT mark
+    the call on the event, so the run would report `finished` on a call nobody
+    answered. ADK's own comment says it is internal.
+    """
+
+    def __init__(
+        self,
+        *,
+        name: str,
+        description: str,
+        asks: Asks = "end_user",
+        fields: list[ApprovalField] | None = None,
+        args: dict[str, Any] | None = None,
+        title: str = "",
+        body: str = "",
+        labels: list[str] | None = None,
+        pending: dict[str, Any] | None = None,
+        describe: Callable[[ApprovalContext], str] | None = None,
+        on_approval: Callable[[ApprovalRequest], Any] | None = None,
+        on_deny: Callable[[ApprovalRequest], Any] | None = None,
+    ) -> None:
+        from google.adk.tools.base_tool import BaseTool  # noqa: PLC0415
+
+        # LAZILY, LIKE `builder.py` DOES ITS MCP IMPORTS. The module must stay
+        # importable where ADK is not installed — a test fixture, a tool that
+        # only validates a manifest — and a hard import at module scope would
+        # make the whole of `agentkit_core.approvals` unimportable there.
+        class _Tool(BaseTool):
+            def __init__(inner) -> None:  # noqa: N805
+                super().__init__(name=name, description=description,
+                                 is_long_running=True)
+
+            def _get_declaration(inner):  # noqa: N805
+                return self._declaration()
+
+            async def run_async(inner, *, args: dict, tool_context):  # noqa: N805
+                return self._file(args, tool_context)
+
+        self.name = name
+        self.description = description
+        self.asks: Asks = asks
+        self.fields = list(fields or [])
+        self.args = dict(args or {})
+        self.title = title or name.replace("_", " ").capitalize()
+        self.body = body
+        self.labels = list(labels or [])
+        #: Extra fields on the INITIAL result the model is handed immediately.
+        #: Merged over the defaults, so a tool can tell the model what to say
+        #: while the request is outstanding.
+        self.pending = dict(pending or {})
+        self.describe = describe
+        self.on_approval = on_approval
+        self.on_deny = on_deny
+        self.adk = _Tool()
+        # THE BACK-REFERENCE THE WALKER FOLLOWS. What a built agent holds is
+        # the ADK tool; what answers a decision is this object, and nothing
+        # else connects them.
+        self.adk._approval_tool = self
+
+    # -- what the model sees ------------------------------------------------
+
+    def _declaration(self):
+        from google.genai import types  # noqa: PLC0415
+
+        properties = {
+            key: types.Schema(type=types.Type.STRING, description=str(hint))
+            for key, hint in self.args.items()
+        }
+        return types.FunctionDeclaration(
+            name=self.name,
+            description=self.description,
+            parameters=types.Schema(type=types.Type.OBJECT,
+                                    properties=properties,
+                                    required=list(properties)),
+        )
+
+    # -- what the store records --------------------------------------------
+
+    def request_spec(self, state: dict[str, Any] | None = None,
+                     args: dict[str, Any] | None = None) -> dict[str, Any]:
+        """The approval this tool raises, as the store should record it.
+
+        EVERY FIELD HERE IS A PROPERTY OF THE TOOL, not of the call — which is
+        why the engine reads it from the instance by name rather than having
+        the body smuggle it out through a contextvar. The first version did
+        that, and it failed in exactly the way that argues against it: ADK runs
+        a tool body where the engine's context does not reach, so the request
+        arrived empty and silently.
+
+        What IS per-call — the arguments the model passed — the action already
+        carries. `state` and `args` are passed only so `describe` can turn them
+        into the card's body; everything else here is fixed at construction.
+        """
+        return {
+            "kind": "approval",
+            "asks": self.asks,
+            "title": self.title,
+            "body": self._describe(state or {}, args or {}),
+            "labels": list(self.labels),
+            "fields": [f.model_dump(mode="json") for f in self.fields],
+        }
+
+    def _describe(self, state: dict[str, Any], args: dict[str, Any]) -> str:
+        """What this request says it is, which may depend on the conversation.
+
+        A STATIC `body` IS OFTEN NOT ENOUGH. "Publish the logbook" does not
+        tell an approver whether they are publishing three entries or three
+        hundred, and the model's own arguments cannot be the answer: those are
+        its account of what it wants, not the record. So `describe` is handed
+        the session state the engine read and returns the sentence.
+
+        A `describe` THAT RAISES FALLS BACK TO `body` rather than leaving the
+        turn paused on a request nobody can see. Failing to word a card is not
+        a reason to lose the approval.
+        """
+        if self.describe is None:
+            return self.body
+        try:
+            said = self.describe(ApprovalContext(
+                tool=self.name, tool_args=dict(args), state=dict(state)))
+        except Exception:
+            logger.exception(
+                "describe() failed for %s; falling back to its static body",
+                self.name)
+            return self.body
+        return str(said) if said else self.body
+
+    # -- the body -----------------------------------------------------------
+
+    def _file(self, args: dict[str, Any], tool_context: Any) -> dict[str, Any]:
+        """The INITIAL RESULT, which is ADK's documented long-running contract.
+
+        A long-running tool returns something immediately; ADK answers the
+        call with it so the model can speak, and a later `FunctionResponse`
+        carrying the same id delivers the real outcome. The call stays on
+        `long_running_tool_ids` throughout, which is what keeps it findable.
+
+        RETURNING NOTHING WAS THE FIRST VERSION AND IT COST A SILENCE. ADK
+        skips building the automatic response only on a falsy return, so the
+        turn suspended with the model having spent its whole output on the
+        function call — a user asked to publish the logbook and saw nothing at
+        all until somebody approved it, minutes later and three messages down.
+
+        IT MUST STAY TRUTHY. An empty dict is falsy, so a `pending` that
+        collapsed to `{}` would silently restore exactly that behaviour.
+
+        AND NOTHING IS CAPTURED HERE. ADK yields the model-response event —
+        where the engine sees the call and files the request — BEFORE calling
+        this, so anything recorded here arrives after the request is already
+        published. A callback reads session state through
+        `ApprovalRequest.state`, which the engine supplies at decision time.
+        """
+        # `pending` FIRST, so `status` cannot be overridden. It is not
+        # decoration: the engine's redelivery guard reads it to tell ADK's own
+        # initial result apart from a real decision, and a tool that replaced
+        # it would make its approval un-answerable.
+        return {
+            **self.pending,
+            "status": AWAITING,
+            # WHO IS BEING ASKED, in the model's own context, so it can say
+            # "the team" rather than inventing an audience.
+            "asks": self.asks,
+            "title": self.title,
+        }
+
+    # -- answering it -------------------------------------------------------
+
+    def callback(self, approved: bool) -> Callable[[ApprovalRequest], Any] | None:
+        return self.on_approval if approved else self.on_deny
+
+
+def coerce_answers(fields: list[ApprovalField],
+                   supplied: dict[str, Any]) -> dict[str, Any]:
+    """The approver's answers, typed against what was declared.
+
+    THE SAME COERCION A LAUNCH FORM GETS, and for the same reason: a form posts
+    strings, and a callback should receive the number it asked for rather than
+    `"3"`. An unknown key is refused rather than dropped — a field somebody
+    thought they were answering and nothing read is worse than an error.
+    """
+    from pydantic import TypeAdapter  # noqa: PLC0415
+
+    from agentkit_core.manifest import PYTHON_TYPES  # noqa: PLC0415
+
+    declared = {f.name: f for f in fields}
+    unknown = sorted(set(supplied) - set(declared))
+    if unknown:
+        raise ValueError(f"this approval has no field named {unknown[0]!r}")
+
+    answers: dict[str, Any] = {}
+    for name, item in declared.items():
+        if name not in supplied or supplied[name] in ("", None):
+            if item.required and item.default is None:
+                raise ValueError(f"{item.label!r} is required")
+            answers[name] = item.default
+            continue
+        value = supplied[name]
+        if item.type == "enum":
+            allowed = [o.value for o in item.options]
+            if value not in allowed:
+                raise ValueError(
+                    f"{item.label!r} must be one of {', '.join(allowed)}")
+            answers[name] = value
+            continue
+        try:
+            answers[name] = TypeAdapter(PYTHON_TYPES[item.type]).validate_python(value)
+        except Exception as exc:  # noqa: BLE001
+            raise ValueError(f"{item.label!r} is not a valid {item.type}") from exc
+    return answers

agentkit_core/artifact_service.py

@@ -0,0 +1,184 @@
+"""`GcsArtifactService` widened with a project scope and an agent scope.
+
+TWO METHODS OVERRIDDEN, AND THAT IS THE WHOLE EXTENSION. ADK composes every
+artifact path through `_get_blob_prefix` — `save`, `load`, `delete`,
+`list_versions`, `get_artifact_version` and `list_artifact_versions` all route
+through it — so widening the layout is one override. `_list_artifact_keys` is
+the single method that builds its prefixes inline instead, which is why it
+needs a second.
+
+WHY THIS LIVES IN `agentkit_core` AND NOT IN THE RUNTIME. Two callers need the
+same layout: the agent pod, and rt-service signing a URL for an upload that
+must land exactly where `load_artifact` will look for it. rt-service cannot
+import the runtime — that would pull `agentkit-plugins` and `mcp` into a
+service that needs neither — and a second copy of the layout is the duplication
+ADR-0116 measured, where both copies pass their own tests and nothing compares
+them. rt-service already pins `google-adk` to the runtime's range for exactly
+this reason, stated in its pyproject: "so the two cannot resolve different
+versions of the schema they share."
+
+ADK IS IMPORTED AT MODULE SCOPE HERE, which is why this is its own module.
+`agentkit_core.artifacts` carries the scope vocabulary with no ADK import at
+all, so a manifest validator or a test fixture can read the rules without the
+framework installed. Only something that actually stores an artifact imports
+this file, and that something has ADK.
+
+WHY A SUBCLASS AND NOT A PARALLEL SERVICE (ADR-0146). `Context.load_artifact`
+passes the filename STRAIGHT THROUGH to whatever artifact service the Runner
+holds, so a reserved filename prefix reaches every scope through
+`tool_context.load_artifact("project:policy.pdf")` with no ADK change and no
+private attribute access. ADK already reserves `user:` for exactly this; these
+are two more of the same kind, not a mechanism beside it.
+
+THE LAYOUT (ADR-0147). The bucket is one project's, so the project scope is
+simply the bucket root outside every agent's folder:
+
+    _project/<name>/<version>                      project:  every agent reads
+    <app_name>.shared/<name>/<version>             agent:    one agent reads
+    <app_name>/<user_id>/user/user:<n>/<version>   user:     ADK's own
+    <app_name>/<user_id>/<session_id>/<n>/<ver>    (bare)    ADK's own
+
+THE PREFIX IS STRIPPED FROM THE STORED PATH FOR THE TWO NEW SCOPES, and kept
+for ADK's. `user:` is part of the name ADK stores, so `_project/project:x/0`
+would be consistent — and it would also be redundant, because the folder it
+sits in already says the scope, and a human browsing the admin panel reads
+these paths. `_list_artifact_keys` puts the prefix back with
+`artifacts.qualify`, which is why that function exists as a documented inverse
+rather than as a convenience.
+
+WHAT THIS CLASS DOES NOT ENFORCE. Refusing an agent's write to a shared scope
+here produces a READABLE error; it is not the boundary. The boundary is a
+managed folder granting `objectViewer`, and a raw 403 surfacing from inside ADK
+names nothing a developer can act on. `allow_shared_writes` is how the one
+caller that legitimately writes them — rt-service, on behalf of a tenant
+admin — opts in, so the pod and the admin route can share this one
+implementation of the layout rather than keeping two.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from google.adk.artifacts import GcsArtifactService
+from google.genai import types
+
+from agentkit_core.artifacts import (
+    ARTIFACT_SCOPE_PREFIXES,
+    SHARED_SCOPES,
+    ArtifactNameRefused,
+    qualify,
+    validate_artifact_filename,
+)
+from agentkit_core.identity import ARTIFACT_PROJECT_FOLDER, ARTIFACT_SHARED_SUFFIX
+
+
+class ScopedGcsArtifactService(GcsArtifactService):
+    """ADK's GCS artifact service plus the project and agent scopes."""
+
+    def __init__(self, bucket_name: str, *, allow_shared_writes: bool = False,
+                 **kwargs: Any) -> None:
+        super().__init__(bucket_name, **kwargs)
+        self.allow_shared_writes = allow_shared_writes
+
+    # --- the layout ---------------------------------------------------------
+
+    def _get_blob_prefix(self, app_name: str, user_id: str, filename: str,
+                         session_id: str | None = None) -> str:
+        """Where this artifact's versions live, for all four scopes.
+
+        VALIDATION HAPPENS HERE BECAUSE EVERY OPERATION PASSES THROUGH HERE.
+        ADK never applies `validate_path_segment` to a filename — deliberately,
+        since a filename may contain `/` — so traversal is ours to refuse, and
+        refusing it in the one place every path is composed means no caller can
+        reach the bucket around it.
+        """
+        scope, name = validate_artifact_filename(filename)
+        if scope == "project":
+            return f"{ARTIFACT_PROJECT_FOLDER}{name}"
+        if scope == "agent":
+            return f"{app_name}{ARTIFACT_SHARED_SUFFIX}/{name}"
+        # `user:` and bare filenames are ADK's own and are left entirely to it,
+        # original filename included — the `user:` prefix is part of the name it
+        # stores, and stripping it here would move every existing blob.
+        return super()._get_blob_prefix(app_name, user_id, filename, session_id)
+
+    def _list_artifact_keys(self, app_name: str, user_id: str,
+                            session_id: str | None) -> list[str]:
+        """ADK's session and user keys, plus the two shared scopes.
+
+        THE PREFIXES ARE PUT BACK, exactly as ADK retains `user:` on the names
+        it returns — a caller that reads a name out of this list must be able
+        to pass it straight back to `load_artifact`, and a bare `policy.pdf`
+        would resolve to the session scope instead.
+
+        A LISTING WITH NO SESSION — AND NO USER — IS LEGITIMATE, AND DELEGATING
+        BLINDLY MADE IT A 500 (ADR-0159). The console's documents page asks for
+        the SHARED scopes, which belong to a project and an agent rather than
+        to anybody's conversation, so it sends neither. ADK's own
+        `_list_artifact_keys` cannot answer that: it validates `user_id`
+        unconditionally and validates `session_id` whenever it is not None, so
+        an empty string raises `session_id must not be empty` from inside a
+        path-segment check — four frames below anything naming a scope.
+
+        The shared scopes depend on NOTHING but `app_name`, which is why they
+        are listed outside that branch. Three readings, each meaningful:
+
+            user and session   all four scopes
+            user, no session   project, agent and that user's own
+            neither            project and agent
+
+        `session_id or None` IS ADK'S OWN SPELLING OF "NO SESSION" rather than
+        a way around its validator: it checks `if session_id is not None` and
+        then lists the session scope only `if session_id`, so None is the value
+        that means absent and "" is the value that means malformed.
+        """
+        if session_id and not user_id:
+            # A SESSION BELONGS TO A USER, so this combination addresses
+            # nothing. Refused rather than quietly dropped: silently ignoring
+            # the session would return a listing that looks complete while
+            # omitting the very scope the caller asked about.
+            raise ArtifactNameRefused(
+                "a session artifact listing needs the user it belongs to; "
+                "pass both, or neither for the project and agent scopes")
+        filenames: set[str] = set()
+        if user_id:
+            filenames |= set(super()._list_artifact_keys(
+                app_name, user_id, session_id or None))
+        for scope, folder in (
+            ("project", ARTIFACT_PROJECT_FOLDER),
+            ("agent", f"{app_name}{ARTIFACT_SHARED_SUFFIX}/"),
+        ):
+            for blob in self.storage_client.list_blobs(self.bucket, prefix=folder):
+                # `<folder><name>/<version>` — the name may itself contain "/",
+                # so drop only the last segment, which is ADK's own rule.
+                tail = blob.name[len(folder):]
+                name = "/".join(tail.split("/")[:-1])
+                if name:
+                    filenames.add(qualify(scope, name))
+        return sorted(filenames)
+
+    # --- the readable half of a boundary IAM enforces -----------------------
+
+    def _refuse_shared_write(self, filename: str, verb: str) -> None:
+        if self.allow_shared_writes:
+            return
+        scope, _ = validate_artifact_filename(filename)
+        if scope in SHARED_SCOPES:
+            raise ArtifactNameRefused(
+                f"an agent may read but not {verb} the {scope} scope "
+                f"({ARTIFACT_SCOPE_PREFIXES[scope]}…); it belongs to the tenant "
+                f"and is managed from the console. This is also enforced by IAM, "
+                f"which would refuse it with no explanation.")
+
+    def _save_artifact(self, app_name: str, user_id: str,
+                       session_id: str | None, filename: str,
+                       artifact: types.Part | dict[str, Any],
+                       custom_metadata: dict[str, Any] | None = None) -> int:
+        self._refuse_shared_write(filename, "write")
+        return super()._save_artifact(app_name, user_id, session_id, filename,
+                                      artifact, custom_metadata)
+
+    def _delete_artifact(self, app_name: str, user_id: str,
+                         session_id: str | None, filename: str) -> None:
+        self._refuse_shared_write(filename, "delete")
+        return super()._delete_artifact(app_name, user_id, session_id, filename)

agentkit_core/artifacts.py

@@ -0,0 +1,33 @@
+"""The four artifact scopes, and what a filename may say.
+
+MOVED TO `elan_agentkit_contracts.artifacts` (ADR-0197), WHICH THIS RE-EXPORTS.
+The scope vocabulary is a PREDICATE every client has to agree on (ADR-0116).
+The SDK validates a filename before asking for an upload ticket and the CLI
+does the same for `elan files put`, so a second copy of the rule would refuse
+names the service accepts — and the reserved prefixes are how `project:` and
+`agent:` reach a wider scope at all.
+
+WHY ANYTHING MOVED AT ALL: `elan-sdk` and `elan-cli` are published to PyPI, and
+a `[tool.uv.sources] … workspace = true` dependency on `agentkit-core` is
+uv-local metadata that never reaches wheel METADATA — so a published wheel
+declared a bare `Requires-Dist: agentkit-core` that pip resolves from an index
+which has never seen it. Publishing `agentkit-core` instead would have shipped
+the token verifiers, the ticket minter, the database layer and the broker to
+every developer who installed the SDK.
+
+THE SHIM EXISTS SO 247 IMPORT SITES DID NOT HAVE TO CHANGE. Every service, the
+runtime, the plugins, the scripts and the test suite keep importing
+`agentkit_core.artifacts`; only the SDK and the CLI were rewritten, because
+they are the two packages that had to stop depending on `agentkit-core` at all.
+Rewriting the rest would have put a branded module name in eight services and
+meant exempting most of the repo from `tests/test_template.py`'s brand scan,
+which is the guard that keeps this repo usable as a starter template.
+
+THE RE-EXPORT HONOURS `__all__`, so a name defined over there and missing from
+that list does not exist here — the quietest possible failure, an ImportError
+at a call site nobody edited. `tests/test_contracts_package.py` walks both
+sides and fails naming the gap.
+"""
+
+from elan_agentkit_contracts.artifacts import *  # noqa: F403
+from elan_agentkit_contracts.artifacts import __all__  # noqa: F401