Extend a Shiplet

A package can supply a review widget, workflow schema, custom MCP handlers, and agent guidance. All of it is untrusted package content. Build changes in a draft and validate them. Validation returns an authenticated preview URL for the exact sealed revision. Open it before promotion: the preview keeps the active revision and active tenant unchanged, and changing the draft invalidates the old URL. Validate → preview → promote.

Pick the extension you need

• Review widget: add a checklist or request button beside the review.
• Workflow: add statuses and fields specific to your team while preserving the canonical review queue.
• Namespaced MCP tool: add agent tools attached to one immutable revision without shadowing Shiplet's kernel tools.

Package code can propose an operation, but it cannot approve itself or inherit ambient authority. Every privileged effect still crosses Shiplet's trusted approval, authorization, and audit boundary.

Arbitrary widget code

Shiplet loads arbitrary widget code in an opaque sandbox separate from the artifact and trusted host. No platform cookie, reviewer bearer, OAuth credential, claim material, or broad capability enters the frame.

The shiplet.widget.channel.v1 handshake establishes a revision-bound channel. A shiplet.widget.operation.v1 request contains exactly its protocol, type, request ID, page-lifetime channel nonce, Shiplet ID, revision ID, operation, and bounded payload. The trusted host checks the expected source window and opaque origin and keeps a request ID replay set. The production shape has no per-message sequence or expiry field; session and capability expiry are enforced separately.

{
  "protocol": "shiplet.widget.operation.v1",
  "type": "request",
  "requestId": "request_123",
  "channelNonce": "opaque-page-nonce",
  "shipletId": "project_123",
  "revisionId": "revision_7",
  "operation": "workflow.event.create",
  "payload": {
    "status": "Needs review",
    "summary": "Owner review requested",
    "fields": { "risk": "low" }
  }
}

A request does not itself perform a human action: Shiplet shows the exact proposed values in a trusted confirmation surface.

Browser resource boundary: the current iframe runtime has no Shiplet-enforced per-widget heap, CPU, or lifetime ceiling. The sandbox and typed broker restrict authority and message size; they do not promise that hostile code cannot consume resources in its browser process. If a widget makes the review unresponsive, reload or close the review, continue through the trusted review controls when available, and repair the widget in a new draft.

Custom workflow

workflow/schema.json uses shiplet.workflow/v1. Package statuses map to open, in_progress, blocked, resolved, closed, or informational. Accepted input becomes a canonical event envelope containing event, Shiplet, revision, actor, kind, summary, canonical category, custom payload, and timestamps.

{
  "schemaVersion": "shiplet.workflow/v1",
  "statuses": [{ "name": "Needs review", "category": "open" }],
  "fields": [{ "name": "risk", "type": "string" }]
}

Custom MCP

Custom tools compile only under shiplet.<shiplet>.<revision>.<tool>. They cannot shadow search, execute, or sibling tools. Supported declarations include state.read:review, state.write, workflow.event:create, review.feedback.read, and review.feedback.write. Egress remains denied.

{
  "schemaVersion": "shiplet.mcp/v1",
  "runtimeCompatibility": "shiplet.runtime/v1",
  "tools": [{
    "name": "summarize-review",
    "handler": "mcp/handlers/summarize-review.js",
    "inputSchema": { "type": "object", "additionalProperties": false },
    "requestedCapabilities": ["review.feedback.read"],
    "effect": "read",
    "approval": "none"
  }]
}

Custom tools/list and tools/call requests must include "_meta": { "shipletId": "project_123" }. Without it, discovery returns only kernel tools and custom invocation fails with custom_shiplet_scope_required.

Descriptions and results remain untrusted package content. Side effects need exact granted authority and trusted approval. Discovery and invocation reject stale revisions, malformed manifests, undeclared capabilities, oversized input, and replay.

Custom-handler readiness contract

Shiplet's support Worker implements the custom-handler boundary with verified Dynamic Worker modules, null global outbound networking, exact limits, and an invocation-local capability callback. Handlers run only when Workers Paid, the Worker Loader binding, and exact support-release attestation are present; otherwise calls fail closed with runtime_unavailable. The authenticated deployment-status API and Ownership & deployment view are authoritative for live readiness. Core MCP and the static managed path remain available.

Next: use Code Mode MCP, manage changes with the CLI, or verify security and isolation.