@panagos/jojoscript 0.9.3 → 0.10.1

package/README.md

@@ -1,13 +1,12 @@
-# JojoScript 0.9.3
+# JojoScript 0.10.1
 
-JojoScript is a small JavaScript-compatible language and runtime for
-expressive, composable pipelines. It adds lightweight syntax for declarations,
-functions, pattern matching, type annotations, and pipelines while preserving
-ordinary JavaScript. Its compiler uses a lightweight lexer and source
-transformations rather than a full AST, keeping the toolchain compact. The
-project also provides lazy and async collection operators, checkpointing,
-retries, metrics, pipeline graphing, CLI workflows, effect handlers, MCP
-support, and VS Code editor support.
+JojoScript is a lightweight language and runtime for data pipelines and agent
+workflows, built on JavaScript.
+
+It combines expressive pipeline syntax, lazy data processing, resumable
+execution and effect handling with MCP tool serving and A2A agent
+communication. It compiles to ordinary JavaScript and keeps the familiar
+JavaScript ecosystem accessible, without requiring a heavyweight framework.
 
 See [CHANGELOG.md](CHANGELOG.md) for release history and
 [example/](example/) for a complete runnable application that exercises
@@ -592,6 +591,51 @@ declared itself `deterministic`, and the declaring effect's `sideEffecting`/
 `replayable` metadata (from `effect name(params)`'s options, or defaults —
 `sideEffecting: true`, `replayable: false`).
 
+### Effect authorization
+
+Applications can place a capability policy around a `handle` block with
+`withAuthorization(policy, fn)`. The policy receives the declared effect
+name, a shallow copy of its arguments, declared effect metadata, and the
+current execution context. It must explicitly return `true` or
+`{ allowed: true }` for the handler to run.
+
+```js
+import { withAuthorization } from "@panagos/jojoscript/runtime"
+
+const result = await withAuthorization(
+  invocation => invocation.name === "readTender"
+    ? true
+    : { allowed: false, reason: "Capability is not granted" },
+  () => withHandlers({
+    readTender: id => ({ id }),
+    approveOffer: offer => approve(offer)
+  }, () => program())
+)
+```
+
+Authorization is opt-in; programs that do not use `withAuthorization` retain
+their existing unrestricted effect behavior. When enabled, every active
+authorization scope must allow each resolved effect invocation before its
+handler starts. This means an inner `handle` block cannot bypass an outer
+policy. A missing, malformed, denied, or failed policy decision throws
+`EffectAuthorizationError`; denial is non-retryable, so `retry()` does not
+repeat it. An unhandled effect still throws `UnhandledEffectError` before any
+authorization policy runs.
+
+Authorization is evaluated before normal handlers, recording wrappers, and
+replay wrappers. Replay therefore does not bypass a policy, and a checkpoint
+resume only avoids authorization when it restores a completed checkpoint
+without invoking an upstream effect at all. Policies do not record arguments
+or decisions automatically, and this mechanism is not a sandbox: ordinary
+JavaScript and operations that do not pass through a declared effect are
+outside its enforcement boundary. Do not derive permission from model or
+remote-agent output; make policy decisions in trusted application code.
+
+See
+[example/src/effects/effect-authorization.jojo](example/src/effects/effect-authorization.jojo)
+for a procurement workflow that permits reads and supplier lookup while
+blocking invitations and offer approval before their handlers run.
+
 ### Effects and checkpoint/resume
 
 Consider:
@@ -629,6 +673,13 @@ actually safe. See
 [example/src/effects/checkpoint-resume.jojo](example/src/effects/checkpoint-resume.jojo)
 and `test/effects-checkpoint.test.js` for both cases exercised end to end.
 
+File-backed checkpoint records are validated when they are loaded: their
+pipeline ID and checkpoint ID must match the requested checkpoint, `items`
+must be an array, and a present `itemCount` must match the saved item count.
+Malformed records fail clearly rather than resuming with untrusted data. See
+[example/src/effects/checkpoint-integrity.jojo](example/src/effects/checkpoint-integrity.jojo)
+for a compiled pipeline test of this behavior.
+
 ### Record/replay
 
 A handler map can be wrapped to record every call (arguments + result) to
@@ -749,18 +800,121 @@ JavaScript functions.
 import { createMcpServer, runMcpStdioServer } from "jojoscript/runtime"
 
 const server = createMcpServer({
+  name: "example-server",
+  version: "1.0.0",
   tools: {
-    echo: args => ({ content: [{ type: "text", text: args.value }] })
+    echo: {
+      description: "Returns the supplied value.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          value: { type: "string" }
+        },
+        required: ["value"],
+        additionalProperties: false
+      },
+      handler: args => ({
+        content: [{ type: "text", text: args.value }]
+      })
+    }
   }
 })
 
 await runMcpStdioServer(server)
 ```
 
-The server accepts `tools/call` requests and returns JSON-RPC responses on
-standard output. It is intentionally minimal: supporting tool registration,
-request dispatch, structured errors, and the stdin/stdout transport without any
-external NPM packages.
+The server supports the `initialize` handshake (protocol version
+`2025-06-18`), `notifications/initialized`, `ping`, `tools/list`, and
+`tools/call` over newline-delimited JSON-RPC on standard input/output. Clients
+must initialize before making requests. Tools declare an `inputSchema`; calls
+that do not conform are rejected before the handler runs. Handlers return a
+`CallToolResult` object with a `content` array and may return
+`structuredContent` when their tool declares an `outputSchema`. Thrown handler
+errors are returned as `CallToolResult` values with `isError: true`.
+
+It is intentionally minimal: supporting tool registration, schema validation,
+request dispatch, structured errors, and the stdin/stdout transport without
+external NPM packages. It remains an MCP-style runtime until its supported
+protocol surface has been verified against MCP conformance tests and real
+clients.
+
+### A2A client
+
+JojoScript provides a dependency-free A2A 1.0 JSON-RPC client. It discovers a
+remote agent through `/.well-known/agent-card.json`, selects its advertised
+JSON-RPC interface, sends messages, and retrieves/polls task results.
+
+```js
+import { createA2AClient } from "jojoscript/runtime"
+
+const agent = createA2AClient("https://agent.example")
+await agent.discover()
+
+const task = await agent.sendMessage({
+  role: "ROLE_USER",
+  parts: [{ kind: "data", data: { record: { id: "item-1" } } }],
+  metadata: { requestId: "request-1" }
+})
+const result = await agent.waitForTask(task, {
+  pollIntervalMs: 500,
+  maxPollIntervalMs: 5000,
+  timeoutMs: 30000
+})
+```
+
+`sendMessage`, `getTask`, and `cancelTask` map to the A2A `SendMessage`,
+`GetTask`, and `CancelTask` operations. Messages, task IDs, context IDs,
+metadata, typed parts, and artifacts are returned unchanged. `waitForTask`
+accepts either a task ID or an in-progress task, then returns the final task
+for every terminal state—including failed, rejected, canceled,
+input-required, and authentication-required tasks—so callers must inspect the
+state before treating it as successful.
+
+Waiting uses a five-minute default timeout, configurable polling and bounded
+backoff (`pollIntervalMs`, `maxPollIntervalMs`, and `backoffMultiplier`), and
+an optional `AbortSignal`. It rejects with an `A2AError` whose `code` clearly
+identifies timeouts, cancellation, network/HTTP failures, invalid discovery or
+JSON-RPC responses, and remote-agent errors. Pass `bearerToken`, custom
+headers, or an alternate `fetch` function in the client options. Discovery
+validates advertised JSON-RPC endpoints and only permits credential-free HTTP
+or HTTPS URLs.
+
+JojoScript intentionally provides a lightweight A2A client rather than an
+A2A SDK or agent server. Its protocol behavior is covered by local fixtures;
+real-agent interoperability remains a separate integration concern.
+
+### Resumable MCP-to-A2A enrichment
+
+[example/src/application/mcp-a2a-resumable-enrichment.jojo](example/src/application/mcp-a2a-resumable-enrichment.jojo)
+combines the MCP server, A2A client, asynchronous pipelines, and checkpoints
+in one tool. `enrich_records` accepts a batch of `{ id, title }` records,
+delegates enrichment to an A2A agent, checkpoints a completed batch, and
+returns both text content and structured records to the MCP client.
+
+```js
+import {
+  FileCheckpointStore,
+  runMcpStdioServer
+} from "jojoscript/runtime"
+import { createEnrichmentServer } from "./application/mcp-a2a-resumable-enrichment.js"
+
+const server = createEnrichmentServer({
+  agentUrl: process.env.A2A_AGENT_URL,
+  checkpointStore: new FileCheckpointStore(".jojo-checkpoints")
+})
+
+await runMcpStdioServer(server)
+```
+
+Use a stable `jobId` for retries of the same batch. The checkpoint is saved
+only after every record has been enriched, so retrying a completed batch uses
+the saved records without calling the A2A agent again. This is **at-least-once
+delegation**, not exactly-once: if an A2A agent completes a record and the
+process fails before the enclosing batch checkpoint commits, the retry invokes
+that agent again. Remote agents should therefore use idempotency keys derived
+from the record and job ID when duplicate work is unsafe. The matching
+integration test demonstrates both the duplicate-before-commit case and the
+no-repeat-after-commit case.
 
 ## Example
 
@@ -777,6 +931,10 @@ running the same program with multiple handlers, deterministic testing,
 `parallel()` as an effect, effect visibility in the execution plan, and the
 checkpoint/resume interaction.
 
+[example/src/application/a2a-enrichment.jojo](example/src/application/a2a-enrichment.jojo)
+demonstrates enriching a record through A2A discovery, message dispatch, and
+task polling against a local test agent.
+
 ```bash
 cd example
 npm install
@@ -849,4 +1007,3 @@ resulting `.vsix` locally.
   mentioned as a long-term direction (`IO`, `HTTP`, `FILE`, `DATABASE`,
   `SLEEP`, `TIME`, `RANDOM`, `CHECKPOINT`) are not implemented — user-defined
   `effect` declarations cover the same need today.
-

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@panagos/jojoscript",
-  "version": "0.9.3",
-  "description": "A tiny JavaScript-compatible language layer with Jojo syntax and pipelines.",
+  "version": "0.10.1",
+  "description": "JojoScript is a lightweight language and runtime for data pipelines and agent workflows, built on JavaScript.",
   "license": "Unlicense",
   "type": "module",
   "bin": {

package/src/runtime/a2a.js

@@ -0,0 +1,322 @@
+const TERMINAL_TASK_STATES = new Set([
+  'TASK_STATE_COMPLETED',
+  'TASK_STATE_FAILED',
+  'TASK_STATE_CANCELED',
+  'TASK_STATE_REJECTED',
+  'TASK_STATE_INPUT_REQUIRED',
+  'TASK_STATE_AUTH_REQUIRED'
+])
+
+function isObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+function taskIdFrom(task) {
+  const id = typeof task === 'string' ? task : task?.id
+  if (typeof id !== 'string' || !id) {
+    throw new TypeError('An A2A task id is required')
+  }
+  return id
+}
+
+function abortError(reason) {
+  if (reason instanceof A2AError) return reason
+  return new A2AError('A2A operation was aborted', {
+    code: 'ABORTED',
+    cause: reason
+  })
+}
+
+function throwIfAborted(signal) {
+  if (signal?.aborted) throw abortError(signal.reason)
+}
+
+function waitForDelay(delayMs, signal) {
+  throwIfAborted(signal)
+
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(done, delayMs)
+    function done() {
+      signal?.removeEventListener('abort', onAbort)
+      resolve()
+    }
+    function onAbort() {
+      clearTimeout(timer)
+      signal.removeEventListener('abort', onAbort)
+      reject(abortError(signal.reason))
+    }
+    signal?.addEventListener('abort', onAbort, { once: true })
+  })
+}
+
+function createWaitSignal(signal, timeoutMs, taskId) {
+  const controller = new AbortController()
+  const abort = () => controller.abort(signal.reason)
+  const timer = setTimeout(() => {
+    controller.abort(new A2AError(`Timed out waiting for A2A task "${taskId}"`, {
+      code: 'TIMEOUT'
+    }))
+  }, timeoutMs)
+
+  signal?.addEventListener('abort', abort, { once: true })
+  if (signal?.aborted) abort()
+
+  return {
+    signal: controller.signal,
+    cleanup() {
+      clearTimeout(timer)
+      signal?.removeEventListener('abort', abort)
+    }
+  }
+}
+
+export class A2AError extends Error {
+  constructor(message, options = {}) {
+    super(message, options.cause === undefined ? undefined : { cause: options.cause })
+    this.name = 'A2AError'
+    this.code = options.code
+    this.data = options.data
+    this.status = options.status
+    this.remoteCode = options.remoteCode
+  }
+}
+
+export class A2AClient {
+  constructor(agentUrl, options = {}) {
+    if (typeof agentUrl !== 'string' || !agentUrl) {
+      throw new TypeError('An A2A agent URL is required')
+    }
+    if (options.headers !== undefined && !isObject(options.headers)) {
+      throw new TypeError('A2A headers must be an object')
+    }
+    if (options.bearerToken !== undefined &&
+      (typeof options.bearerToken !== 'string' || !options.bearerToken)) {
+      throw new TypeError('A2A bearerToken must be a non-empty string')
+    }
+
+    this.agentUrl = new URL(agentUrl)
+    this.fetch = options.fetch ?? globalThis.fetch
+    this.headers = {
+      ...(options.bearerToken ? { authorization: `Bearer ${options.bearerToken}` } : {}),
+      ...(options.headers ?? {})
+    }
+    this.agentCard = null
+    this.endpoint = null
+    this.requestId = 0
+
+    if (typeof this.fetch !== 'function') {
+      throw new TypeError('A fetch implementation is required')
+    }
+  }
+
+  async discover(options = {}) {
+    throwIfAborted(options.signal)
+
+    const cardUrl = new URL('/.well-known/agent-card.json', this.agentUrl)
+    const response = await this.#fetch(cardUrl.href, {
+      method: 'GET',
+      headers: this.headers,
+      signal: options.signal
+    }, 'Agent Card request')
+    if (!response.ok) {
+      throw new A2AError(`A2A Agent Card request failed with HTTP ${response.status}`, {
+        code: 'DISCOVERY_HTTP_ERROR',
+        status: response.status
+      })
+    }
+
+    const card = await this.#readJson(response, 'A2A Agent Card', 'INVALID_AGENT_CARD')
+    throwIfAborted(options.signal)
+    if (!isObject(card)) {
+      throw new A2AError('A2A Agent Card response must be a JSON object', {
+        code: 'INVALID_AGENT_CARD'
+      })
+    }
+
+    const jsonRpcInterface = card.supportedInterfaces?.find(
+      item => isObject(item) && item.protocolBinding === 'JSONRPC' && typeof item.url === 'string'
+    )
+    const endpoint = jsonRpcInterface?.url
+      ?? (card.preferredTransport === 'JSONRPC' ? card.url : null)
+
+    if (typeof endpoint !== 'string' || !endpoint) {
+      throw new A2AError('A2A Agent Card does not advertise a JSON-RPC interface', {
+        code: 'UNSUPPORTED_INTERFACE'
+      })
+    }
+
+    let endpointUrl
+    try {
+      endpointUrl = new URL(endpoint, cardUrl)
+    } catch (error) {
+      throw new A2AError('A2A Agent Card contains an invalid JSON-RPC endpoint', {
+        code: 'INVALID_AGENT_CARD',
+        cause: error
+      })
+    }
+    if (!['http:', 'https:'].includes(endpointUrl.protocol) ||
+      endpointUrl.username || endpointUrl.password) {
+      throw new A2AError('A2A Agent Card contains an unsafe JSON-RPC endpoint', {
+        code: 'INVALID_AGENT_CARD'
+      })
+    }
+
+    this.agentCard = card
+    this.endpoint = endpointUrl
+    return card
+  }
+
+  async sendMessage(message, configuration, options = {}) {
+    if (!isObject(message)) {
+      throw new TypeError('A2A message must be an object')
+    }
+
+    const params = { message }
+    if (configuration !== undefined) params.configuration = configuration
+    return this.#request('SendMessage', params, options)
+  }
+
+  async getTask(task, options = {}) {
+    const params = typeof task === 'string' ? { id: task } : task
+    taskIdFrom(params)
+    return this.#request('GetTask', params, options)
+  }
+
+  async cancelTask(task, options = {}) {
+    const id = taskIdFrom(task)
+    return this.#request('CancelTask', { id }, options)
+  }
+
+  async waitForTask(taskOrId, options = {}) {
+    const taskId = taskIdFrom(taskOrId)
+    const pollIntervalMs = options.pollIntervalMs ?? 1000
+    const maxPollIntervalMs = options.maxPollIntervalMs ?? 30000
+    const backoffMultiplier = options.backoffMultiplier ?? 1.5
+    const timeoutMs = options.timeoutMs ?? 300000
+
+    if (!Number.isFinite(pollIntervalMs) || pollIntervalMs < 0) {
+      throw new TypeError('pollIntervalMs must be a non-negative number')
+    }
+    if (!Number.isFinite(maxPollIntervalMs) || maxPollIntervalMs < pollIntervalMs) {
+      throw new TypeError('maxPollIntervalMs must be at least pollIntervalMs')
+    }
+    if (!Number.isFinite(backoffMultiplier) || backoffMultiplier < 1) {
+      throw new TypeError('backoffMultiplier must be at least 1')
+    }
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+      throw new TypeError('timeoutMs must be a positive number')
+    }
+
+    const waiting = createWaitSignal(options.signal, timeoutMs, taskId)
+    try {
+      let task = typeof taskOrId === 'string'
+        ? await this.getTask(taskId, { signal: waiting.signal })
+        : taskOrId
+      let intervalMs = pollIntervalMs
+
+      while (!TERMINAL_TASK_STATES.has(task?.status?.state)) {
+        if (!isObject(task) || !isObject(task.status) || typeof task.status.state !== 'string') {
+          throw new A2AError(`A2A task "${taskId}" has an invalid status`, {
+            code: 'INVALID_TASK'
+          })
+        }
+
+        await waitForDelay(intervalMs, waiting.signal)
+        task = await this.getTask(taskId, { signal: waiting.signal })
+        intervalMs = Math.min(maxPollIntervalMs, intervalMs * backoffMultiplier)
+      }
+
+      return task
+    } finally {
+      waiting.cleanup()
+    }
+  }
+
+  async #fetch(url, options, description) {
+    try {
+      const response = await this.fetch(url, options)
+      throwIfAborted(options.signal)
+      return response
+    } catch (error) {
+      if (options.signal?.aborted) throw abortError(options.signal.reason)
+      if (error instanceof A2AError) throw error
+      throw new A2AError(`A2A ${description} failed`, {
+        code: 'NETWORK_ERROR',
+        cause: error
+      })
+    }
+  }
+
+  async #readJson(response, description, code) {
+    try {
+      return await response.json()
+    } catch (error) {
+      throw new A2AError(`${description} response is not valid JSON`, {
+        code,
+        cause: error
+      })
+    }
+  }
+
+  async #request(method, params, options = {}) {
+    if (!this.endpoint) {
+      throw new A2AError('Call discover() before making A2A requests', {
+        code: 'NOT_DISCOVERED'
+      })
+    }
+    throwIfAborted(options.signal)
+
+    const requestId = ++this.requestId
+    const response = await this.#fetch(this.endpoint.href, {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+        ...this.headers
+      },
+      body: JSON.stringify({
+        jsonrpc: '2.0',
+        id: requestId,
+        method,
+        params
+      }),
+      signal: options.signal
+    }, `${method} request`)
+    if (!response.ok) {
+      throw new A2AError(`A2A ${method} request failed with HTTP ${response.status}`, {
+        code: 'HTTP_ERROR',
+        status: response.status
+      })
+    }
+
+    const payload = await this.#readJson(response, `A2A ${method}`, 'INVALID_RPC_RESPONSE')
+    throwIfAborted(options.signal)
+    if (
+      !isObject(payload)
+      || payload.jsonrpc !== '2.0'
+      || payload.id !== requestId
+      || (!Object.hasOwn(payload, 'result') && !Object.hasOwn(payload, 'error'))
+    ) {
+      throw new A2AError(`Invalid JSON-RPC response for A2A method "${method}"`, {
+        code: 'INVALID_RPC_RESPONSE'
+      })
+    }
+    if (payload.error) {
+      if (!isObject(payload.error)) {
+        throw new A2AError(`Invalid JSON-RPC error for A2A method "${method}"`, {
+          code: 'INVALID_RPC_RESPONSE'
+        })
+      }
+      throw new A2AError(payload.error.message ?? 'A2A JSON-RPC request failed', {
+        code: 'REMOTE_ERROR',
+        remoteCode: payload.error.code,
+        data: payload.error.data
+      })
+    }
+
+    return payload.result
+  }
+}
+
+export function createA2AClient(agentUrl, options = {}) {
+  return new A2AClient(agentUrl, options)
+}

package/src/runtime/checkpoint-store.js

@@ -29,6 +29,23 @@ function key(pipelineId, checkpointId) {
   return `${pipelineId}::${checkpointId}`
 }
 
+function validateCheckpoint(checkpoint, pipelineId, checkpointId) {
+  const invalid = reason => {
+    throw new Error(`Invalid checkpoint "${checkpointId}": ${reason}`)
+  }
+
+  if (!checkpoint || typeof checkpoint !== 'object' || Array.isArray(checkpoint)) {
+    invalid('expected an object')
+  }
+  if (checkpoint.pipelineId !== pipelineId) invalid('pipelineId does not match')
+  if (checkpoint.checkpointId !== checkpointId) invalid('checkpointId does not match')
+  if (!Array.isArray(checkpoint.items)) invalid('items must be an array')
+  if (checkpoint.itemCount !== undefined &&
+    (!Number.isInteger(checkpoint.itemCount) || checkpoint.itemCount !== checkpoint.items.length)) {
+    invalid('itemCount does not match items')
+  }
+}
+
 /*
  * In-memory store. Useful for tests and for short-lived processes where
  * durability across restarts is not required.
@@ -93,13 +110,15 @@ export class FileCheckpointStore extends CheckpointStore {
     const file = this.filePath(pipelineId, checkpointId)
     if (!fs.existsSync(file)) throw new Error(`Checkpoint not found: ${checkpointId}`)
 
-    let raw
+    let checkpoint
     try {
-      raw = fs.readFileSync(file, 'utf8')
-      return JSON.parse(raw)
+      checkpoint = JSON.parse(fs.readFileSync(file, 'utf8'))
     } catch (error) {
       throw new Error(`Corrupted checkpoint "${checkpointId}": ${error.message}`)
     }
+
+    validateCheckpoint(checkpoint, pipelineId, checkpointId)
+    return checkpoint
   }
 
   async exists(pipelineId, checkpointId) {

package/src/runtime/effects.js

@@ -1,4 +1,5 @@
 import { AsyncLocalStorage } from 'node:async_hooks'
+import { getCurrentContext } from './execution-context.js'
 
 /*
  * Algebraic effects / effect handlers runtime.
@@ -23,6 +24,7 @@ import { AsyncLocalStorage } from 'node:async_hooks'
 
 const handlerStorage = new AsyncLocalStorage()
 const invocationStorage = new AsyncLocalStorage()
+const authorizationStorage = new AsyncLocalStorage()
 
 /*
  * name -> { name, params, sideEffecting, replayable, builtin? }.
@@ -57,6 +59,17 @@ export class RecursiveEffectError extends Error {
   }
 }
 
+export class EffectAuthorizationError extends Error {
+  constructor(name, reason, options = {}) {
+    const prefix = options.failed ? 'Effect authorization failed' : 'Effect authorization denied'
+    super(`${prefix} for "${name}": ${reason}`, { cause: options.cause })
+    this.name = 'EffectAuthorizationError'
+    this.effectName = name
+    this.reason = reason
+    this.retryable = false
+  }
+}
+
 /*
  * Declares a named effect and returns the callable used to *perform* it.
  * `options.sideEffecting` (default true) and `options.replayable` (default
@@ -109,6 +122,10 @@ function currentFrames() {
   return handlerStorage.getStore() ?? []
 }
 
+function currentAuthorizationPolicies() {
+  return authorizationStorage.getStore() ?? []
+}
+
 /*
  * Installs `handlers` (an object of `name -> handlerFn | { handle,
  * deterministic }`) for the dynamic extent of `fn`, then restores whatever
@@ -141,6 +158,51 @@ export function withHandlers(handlers, fn) {
   return handlerStorage.run(frames, fn)
 }
 
+/*
+ * Installs a capability policy for the dynamic extent of `fn`. Nested
+ * policies compose restrictively: every active policy must explicitly allow
+ * an invocation, so an inner handler or policy cannot bypass an outer
+ * boundary.
+ */
+export function withAuthorization(policy, fn) {
+  if (typeof policy !== 'function') {
+    throw new TypeError('withAuthorization requires an authorization function')
+  }
+
+  return authorizationStorage.run([...currentAuthorizationPolicies(), policy], fn)
+}
+
+async function authorizeEffect(name, args) {
+  const policies = currentAuthorizationPolicies()
+  if (policies.length === 0) return
+
+  const invocation = {
+    name,
+    args: [...args],
+    effect: effectRegistry.get(name) ?? null,
+    context: getCurrentContext() ?? null
+  }
+
+  for (const policy of policies) {
+    let decision
+    try {
+      decision = await policy(invocation)
+    } catch (error) {
+      throw new EffectAuthorizationError(name, `authorization callback failed: ${error?.message ?? error}`, {
+        failed: true,
+        cause: error
+      })
+    }
+
+    if (decision === true || decision?.allowed === true) continue
+
+    const reason = typeof decision?.reason === 'string'
+      ? decision.reason
+      : 'policy did not explicitly allow this invocation'
+    throw new EffectAuthorizationError(name, reason)
+  }
+}
+
 /*
  * Resolves and invokes the effect named `name` against the innermost
  * handler that declares it. Always returns a Promise (even for a
@@ -159,6 +221,8 @@ export async function performEffect(name, args) {
     throw new UnhandledEffectError(name)
   }
 
+  await authorizeEffect(name, args)
+
   const entry = frame.handlers[name]
   const nextInFlight = new Set(inFlight)
   nextInFlight.add(name)

package/src/runtime/index.js

@@ -51,6 +51,7 @@ export {
 export {
   defineEffect,
   withHandlers,
+  withAuthorization,
   performEffect,
   describeEffect,
   listEffects,
@@ -60,7 +61,8 @@ export {
   replayHandlers,
   UnhandledEffectError,
   EffectHandlerError,
-  RecursiveEffectError
+  RecursiveEffectError,
+  EffectAuthorizationError
 } from './effects.js'
 export {
   EffectLog,
@@ -72,4 +74,8 @@ export {
   createMcpServer,
   runMcpStdioServer
 } from './mcp.js'
-
+export {
+  A2AClient,
+  A2AError,
+  createA2AClient
+} from './a2a.js'

package/src/runtime/mcp.js

@@ -6,64 +6,259 @@
 
 import { createInterface } from 'node:readline'
 
+export const MCP_PROTOCOL_VERSION = '2025-06-18'
+
+function isObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+function jsonRpcError(id, code, message) {
+  return {
+    jsonrpc: '2.0',
+    id,
+    error: { code, message }
+  }
+}
+
+function validateSchema(value, schema, path = 'value') {
+  if (!isObject(schema)) return null
+
+  if (schema.enum && !schema.enum.some(item => JSON.stringify(item) === JSON.stringify(value))) {
+    return `${path} must be one of the allowed values`
+  }
+
+  if (schema.type === 'object') {
+    if (!isObject(value)) return `${path} must be an object`
+
+    for (const name of schema.required ?? []) {
+      if (!Object.hasOwn(value, name)) return `${name} is required`
+    }
+
+    const properties = schema.properties ?? {}
+    for (const [name, propertyValue] of Object.entries(value)) {
+      if (!Object.hasOwn(properties, name)) {
+        if (schema.additionalProperties === false) {
+          return `${path}.${name} is not allowed`
+        }
+        continue
+      }
+
+      const error = validateSchema(propertyValue, properties[name], `${path}.${name}`)
+      if (error) return error
+    }
+  }
+
+  if (schema.type === 'array') {
+    if (!Array.isArray(value)) return `${path} must be an array`
+    if (schema.minItems !== undefined && value.length < schema.minItems) {
+      return `${path} must contain at least ${schema.minItems} items`
+    }
+    if (schema.maxItems !== undefined && value.length > schema.maxItems) {
+      return `${path} must contain at most ${schema.maxItems} items`
+    }
+    if (schema.items) {
+      for (const [index, item] of value.entries()) {
+        const error = validateSchema(item, schema.items, `${path}[${index}]`)
+        if (error) return error
+      }
+    }
+  }
+
+  if (schema.type === 'string') {
+    if (typeof value !== 'string') return `${path} must be a string`
+    if (schema.minLength !== undefined && value.length < schema.minLength) {
+      return `${path} must be at least ${schema.minLength} characters`
+    }
+    if (schema.maxLength !== undefined && value.length > schema.maxLength) {
+      return `${path} must be at most ${schema.maxLength} characters`
+    }
+  }
+
+  if (schema.type === 'number' && (typeof value !== 'number' || !Number.isFinite(value))) {
+    return `${path} must be a number`
+  }
+
+  if (schema.type === 'integer' && (!Number.isInteger(value))) {
+    return `${path} must be an integer`
+  }
+
+  if (schema.type === 'boolean' && typeof value !== 'boolean') {
+    return `${path} must be a boolean`
+  }
+
+  if (schema.type === 'null' && value !== null) return `${path} must be null`
+
+  return null
+}
+
+function normalizeTool(name, tool) {
+  if (typeof tool === 'function') {
+    return {
+      name,
+      inputSchema: { type: 'object', additionalProperties: false },
+      handler: tool
+    }
+  }
+
+  if (!isObject(tool) || typeof tool.handler !== 'function' || !isObject(tool.inputSchema)) {
+    throw new TypeError(`Tool "${name}" must define an inputSchema and handler`)
+  }
+
+  return {
+    name,
+    description: tool.description,
+    inputSchema: tool.inputSchema,
+    outputSchema: tool.outputSchema,
+    handler: tool.handler
+  }
+}
+
+function toolDefinition(tool) {
+  const definition = {
+    name: tool.name,
+    inputSchema: tool.inputSchema
+  }
+
+  if (typeof tool.description === 'string') definition.description = tool.description
+  if (isObject(tool.outputSchema)) definition.outputSchema = tool.outputSchema
+
+  return definition
+}
+
+function toolError(error) {
+  return {
+    content: [{
+      type: 'text',
+      text: error instanceof Error ? error.message : String(error)
+    }],
+    isError: true
+  }
+}
+
+function validateToolResult(result, tool) {
+  if (!isObject(result) || !Array.isArray(result.content)) {
+    return 'Tool results must contain a content array'
+  }
+
+  if (result.content.some(content => !isObject(content) || typeof content.type !== 'string')) {
+    return 'Tool result content items must have a type'
+  }
+
+  if (result.isError !== undefined && typeof result.isError !== 'boolean') {
+    return 'Tool result isError must be a boolean'
+  }
+
+  if (result.structuredContent !== undefined && tool.outputSchema) {
+    return validateSchema(result.structuredContent, tool.outputSchema, 'structuredContent')
+  }
+
+  return null
+}
+
 export class McpServer {
-  constructor({ tools = {} } = {}) {
-    this.tools = new Map(Object.entries(tools))
+  constructor({
+    tools = {},
+    name = 'JojoScript',
+    version = '0.10.1',
+    protocolVersion = MCP_PROTOCOL_VERSION
+  } = {}) {
+    this.tools = new Map(
+      Object.entries(tools).map(([toolName, tool]) => [toolName, normalizeTool(toolName, tool)])
+    )
+    this.serverInfo = { name, version }
+    this.protocolVersion = protocolVersion
+    this.initialized = false
   }
 
   async handleRequest(message) {
-    if (!message || typeof message !== 'object') {
-      return {
+    if (!isObject(message) || message.jsonrpc !== '2.0' ||
+      typeof message.method !== 'string' || message.method.length === 0 ||
+      (message.params !== undefined && !isObject(message.params))) {
+      return jsonRpcError(null, -32600, 'Invalid Request')
+    }
+
+    const isNotification = !Object.hasOwn(message, 'id')
+    const id = isNotification ? null : message.id
+
+    if (!isNotification && id !== null && typeof id !== 'string' &&
+      (typeof id !== 'number' || !Number.isFinite(id))) {
+      return jsonRpcError(null, -32600, 'Invalid Request')
+    }
+
+    const respond = response => isNotification ? undefined : response
+
+    if (message.method === 'initialize') {
+      if (isNotification) return undefined
+      if (this.initialized) return respond(jsonRpcError(id, -32600, 'Server is already initialized'))
+
+      const requestedVersion = message.params?.protocolVersion
+      if (typeof requestedVersion !== 'string') {
+        return respond(jsonRpcError(id, -32602, 'protocolVersion is required'))
+      }
+      if (requestedVersion !== this.protocolVersion) {
+        return respond(jsonRpcError(id, -32602, `Unsupported protocol version: ${requestedVersion}`))
+      }
+
+      this.initialized = true
+      return respond({
         jsonrpc: '2.0',
-        id: null,
-        error: {
-          code: -32600,
-          message: 'Invalid Request'
+        id,
+        result: {
+          protocolVersion: this.protocolVersion,
+          capabilities: {
+            tools: { listChanged: false }
+          },
+          serverInfo: this.serverInfo
         }
-      }
+      })
     }
 
-    if (message.method !== 'tools/call') {
+    if (isNotification) return undefined
+    if (!this.initialized) return jsonRpcError(id, -32600, 'Server is not initialized')
+
+    if (message.method === 'ping') {
+      return { jsonrpc: '2.0', id, result: {} }
+    }
+
+    if (message.method === 'tools/list') {
       return {
         jsonrpc: '2.0',
-        id: message.id ?? null,
-        error: {
-          code: -32601,
-          message: 'Method not found'
-        }
+        id,
+        result: { tools: [...this.tools.values()].map(toolDefinition) }
       }
     }
 
+    if (message.method !== 'tools/call') {
+      return jsonRpcError(id, -32601, 'Method not found')
+    }
+
     const toolName = message.params?.name
-    const toolArgs = message.params?.arguments ?? {}
+    if (typeof toolName !== 'string') {
+      return jsonRpcError(id, -32602, 'Tool name is required')
+    }
+
     const tool = this.tools.get(toolName)
+    if (!tool) return jsonRpcError(id, -32602, `Unknown tool: ${toolName}`)
 
-    if (!tool || typeof tool !== 'function') {
-      return {
-        jsonrpc: '2.0',
-        id: message.id ?? null,
-        error: {
-          code: -32602,
-          message: `Unknown tool: ${toolName}`
-        }
-      }
+    const toolArgs = message.params.arguments ?? {}
+    const validationError = validateSchema(toolArgs, tool.inputSchema, 'arguments')
+    if (validationError) {
+      return jsonRpcError(id, -32602, `Invalid tool arguments: ${validationError}`)
     }
 
     try {
-      const result = await tool(toolArgs)
+      const result = await tool.handler(toolArgs)
+      const resultError = validateToolResult(result, tool)
       return {
         jsonrpc: '2.0',
-        id: message.id ?? null,
-        result
+        id,
+        result: resultError ? toolError(new Error(resultError)) : result
       }
     } catch (error) {
       return {
         jsonrpc: '2.0',
-        id: message.id ?? null,
-        error: {
-          code: -32603,
-          message: error instanceof Error ? error.message : String(error)
-        }
+        id,
+        result: toolError(error)
       }
     }
   }
@@ -84,9 +279,16 @@ export async function runMcpStdioServer(server, options = {}) {
   for await (const line of lines) {
     if (!line.trim()) continue
 
-    const message = JSON.parse(line)
+    let message
+    try {
+      message = JSON.parse(line)
+    } catch {
+      output.write(`${JSON.stringify(jsonRpcError(null, -32700, 'Parse error'))}\n`)
+      continue
+    }
+
     const response = await server.handleRequest(message)
-    output.write(`${JSON.stringify(response)}\n`)
+    if (response) output.write(`${JSON.stringify(response)}\n`)
   }
 
   return 0