@panagos/jojoscript 0.9.3 → 1.0.0

package/src/runtime/checkpoint-store.js

@@ -1,5 +1,7 @@
 import fs from 'node:fs'
-import path from 'node:path'
+import path from 'node:path'
+
+import { toJson, fromJson } from './serialization.js'
 
 /*
  * Storage interface for checkpoints. Deliberately storage-agnostic: the
@@ -29,6 +31,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.
@@ -85,7 +104,7 @@ export class FileCheckpointStore extends CheckpointStore {
     fs.mkdirSync(path.dirname(file), { recursive: true })
 
     const tmp = `${file}.tmp-${process.pid}-${Date.now()}`
-    fs.writeFileSync(tmp, JSON.stringify(checkpoint), 'utf8')
+    fs.writeFileSync(tmp, toJson(checkpoint), 'utf8')
     fs.renameSync(tmp, file)
   }
 
@@ -93,13 +112,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 = fromJson(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/checkpoint.js

@@ -1,4 +1,5 @@
-import { getCurrentContext, getDefaultContext } from './execution-context.js'
+import { getCurrentContext, getDefaultContext } from './execution-context.js'
+import { now } from './effects.js'
 
 /*
  * A pipeline checkpoint. `items` flow through unchanged; the operator's job
@@ -64,6 +65,6 @@ export async function* checkpoint(items, name, meta = {}) {
     checkpointId: name,
     items: buffer,
     itemCount: buffer.length,
-    createdAt: new Date().toISOString()
+    createdAt: new Date(now()).toISOString()
   })
 }

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,8 @@ import { AsyncLocalStorage } from 'node:async_hooks'
 
 const handlerStorage = new AsyncLocalStorage()
 const invocationStorage = new AsyncLocalStorage()
+const authorizationStorage = new AsyncLocalStorage()
+const deterministicStorage = new AsyncLocalStorage()
 
 /*
  * name -> { name, params, sideEffecting, replayable, builtin? }.
@@ -57,6 +60,26 @@ 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
+  }
+}
+
+export class NondeterministicEffectError extends Error {
+  constructor(name) {
+    super(`Effect "${name}" has no deterministic handler; inside deterministic mode use { handle, deterministic: true } or replayHandlers`)
+    this.name = 'NondeterministicEffectError'
+    this.effectName = name
+    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 +132,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 +168,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
@@ -160,6 +232,12 @@ export async function performEffect(name, args) {
   }
 
   const entry = frame.handlers[name]
+  if (deterministicStorage.getStore() && entry.deterministic !== true) {
+    throw new NondeterministicEffectError(name)
+  }
+
+  await authorizeEffect(name, args)
+
   const nextInFlight = new Set(inFlight)
   nextInFlight.add(name)
 
@@ -216,9 +294,65 @@ effectRegistry.set('PARALLEL', {
   builtin: true
 })
 
+for (const [name, params] of [['TIME', []], ['RANDOM', []]]) {
+  effectRegistry.set(name, { name, params, sideEffecting: false, replayable: false, builtin: true })
+}
+
+function builtinHandler(name) {
+  const frame = currentFrames().find(f => name in f.handlers)
+  return frame ? frame.handlers[name].handle : null
+}
+
 export function getParallelHandler() {
-  const frame = currentFrames().find(f => 'PARALLEL' in f.handlers)
-  return frame ? frame.handlers.PARALLEL.handle : null
+  return builtinHandler('PARALLEL')
+}
+
+/*
+ * `now()` and `random()` are built-in capabilities like `PARALLEL`: they are
+ * synchronous, fall back to `Date.now()` / `Math.random()`, and can be
+ * replaced with `handle { TIME: ..., RANDOM: ... }` or `deterministic()`.
+ */
+export function now() {
+  const handler = builtinHandler('TIME')
+  return handler ? handler() : Date.now()
+}
+
+export function random() {
+  const handler = builtinHandler('RANDOM')
+  return handler ? handler() : Math.random()
+}
+
+// mulberry32: a small, well-distributed seeded generator.
+function seededRandom(seed) {
+  let state = seed >>> 0
+  return () => {
+    state = (state + 0x6D2B79F5) >>> 0
+    let t = state
+    t = Math.imul(t ^ (t >>> 15), t | 1)
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61)
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296
+  }
+}
+
+async function* runSequentially({ items, fn }) {
+  for await (const item of items) yield await fn(item)
+}
+
+/*
+ * Runs `fn` so that the same inputs always produce the same outputs: a seeded
+ * `random()`, a clock that starts at `startTime` and advances 1ms per read,
+ * sequential `parallel()`, and only effects whose handler is declared
+ * deterministic (including replay handlers).
+ */
+export function deterministic(fn, options = {}) {
+  let clock = options.startTime ?? 0
+  const handlers = {
+    TIME: { handle: () => clock++, deterministic: true },
+    RANDOM: { handle: seededRandom(options.seed ?? 1), deterministic: true },
+    PARALLEL: { handle: runSequentially, deterministic: true }
+  }
+
+  return deterministicStorage.run(true, () => withHandlers(handlers, fn))
 }
 
 /*

package/src/runtime/errors.js

@@ -27,3 +27,17 @@ export class PipelineError extends Error {
     this.timestamp = details.timestamp ?? new Date().toISOString()
   }
 }
+
+/*
+ * A broken `requires`/`ensures` clause is a programming error, so retrying
+ * the same call can never succeed.
+ */
+export class ContractError extends NonRetryableError {
+  constructor(functionName, kind, condition) {
+    super(`Contract violated: ${functionName} ${kind} ${condition}`)
+    this.name = 'ContractError'
+    this.functionName = functionName
+    this.kind = kind
+    this.condition = condition
+  }
+}

package/src/runtime/index.js

@@ -31,10 +31,12 @@ export {
 } from './collections.js'
 
 export { checkpoint } from './checkpoint.js'
+export { toJson, fromJson } from './serialization.js'
+export { defineType } from './tagged-unions.js'
 export { inspect, formatInspectReport } from './inspect.js'
 export { retry } from './retry.js'
 export { traceNode } from './trace.js'
-export { PipelineError, NonRetryableError } from './errors.js'
+export { PipelineError, NonRetryableError, ContractError } from './errors.js'
 export { Metrics, throughputOf } from './metrics.js'
 export {
   CheckpointStore,
@@ -51,6 +53,7 @@ export {
 export {
   defineEffect,
   withHandlers,
+  withAuthorization,
   performEffect,
   describeEffect,
   listEffects,
@@ -60,7 +63,12 @@ export {
   replayHandlers,
   UnhandledEffectError,
   EffectHandlerError,
-  RecursiveEffectError
+  RecursiveEffectError,
+  EffectAuthorizationError,
+  NondeterministicEffectError,
+  deterministic,
+  now,
+  random
 } from './effects.js'
 export {
   EffectLog,
@@ -72,4 +80,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 = '1.0.0',
+    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