npm - @pikku/addon-console - Versions diffs - 0.12.34 → 0.12.36 - Mend

@pikku/addon-console 0.12.34 → 0.12.36

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (123) hide show

package/dist/.pikku/schemas/schemas/AddonPackageInfo.schema.json CHANGED Viewed

	@@ -1 +1 @@
1	- { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "displayName": { "type": "string" }, "version": { "type": "string" }, "description": { "type": "string" }, "author": { "type": "string" }, "repository": { "type": "string" }, "license": { "type": "string" }, "readme": { "type": "string" }, "icon": { "type": "string" }, "publishedAt": { "type": "string" }, "updatedAt": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "categories": { "type": "array", "items": { "type": "string" } }, "functions": { "$ref": "#/definitions/FunctionsMeta" }, "agents": { "type": "object", "additionalProperties": {} }, "secrets": { "type": "object", "additionalProperties": {} }, "credentials": { "type": "object", "additionalProperties": {}, "description": "OAuth2 + wire credentials the addon declares (from its own `credentials/pikku-credentials-meta.gen.json`). Entries with an `oauth2` field are OAuth integrations to connect; the rest are wire credentials." }, "variables": { "type": "object", "additionalProperties": {} }, "httpRoutes": { "$ref": "#/definitions/HTTPWiringsMeta" }, "channels": { "$ref": "#/definitions/ChannelsMeta" }, "cli": { "type": "object", "additionalProperties": { "$ref": "#/definitions/CLIProgramMeta" } }, "mcp": { "anyOf": [{ "$ref": "#/definitions/McpMeta" }, { "type": "null" }] }, "schemas": { "type": "object", "additionalProperties": {} } }, "required": ["id", "name", "displayName", "version", "description", "author", "publishedAt", "updatedAt", "tags", "categories", "functions", "agents", "secrets", "credentials", "variables", "httpRoutes", "channels", "cli", "mcp", "schemas"], "additionalProperties": false, "definitions": { "FunctionsMeta": { "type": "object", "additionalProperties": { "$ref": "#/definitions/FunctionMeta" } }, "FunctionMeta": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string" }, "functionType": { "type": "string", "enum": ["user", "inline", "helper"] }, "funcWrapper": { "type": "string" }, "services": { "$ref": "#/definitions/FunctionServicesMeta" }, "wires": { "$ref": "#/definitions/FunctionWiresMeta" }, "inputs": { "anyOf": [{ "type": "array", "items": { "type": "string" } }, { "type": "null" }] }, "outputs": { "anyOf": [{ "type": "array", "items": { "type": "string" } }, { "type": "null" }] }, "middleware": { "type": "array", "items": { "$ref": "#/definitions/MiddlewareMetadata" } }, "permissions": { "type": "array", "items": { "$ref": "#/definitions/PermissionMetadata" } }, "isDirectFunction": { "type": "boolean" }, "sourceFile": { "type": "string" }, "exportedName": { "type": "string" }, "bodySourceFile": { "type": "string", "description": "File containing the handler body when it differs from sourceFile (imported handlers)" }, "bodyStart": { "type": "number", "description": "1-indexed first line of the handler body (verbose meta; coverage mapping)" }, "bodyEnd": { "type": "number", "description": "1-indexed last line of the handler body (verbose meta; coverage mapping)" }, "pikkuFuncId": { "type": "string" }, "packageName": { "type": "string" }, "title": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "summary": { "type": "string" }, "description": { "type": "string" }, "errors": { "type": "array", "items": { "type": "string" } }, "inputSchemaName": { "type": ["string", "null"] }, "outputSchemaName": { "type": ["string", "null"] }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "Scopes the session must hold to run this function. All are required (AND)." }, "expose": { "type": "boolean" }, "remote": { "type": "boolean" }, "scenarioStep": { "type": "boolean", "description": "A step RPC: a name dispatched by a scenario run and refused everywhere else. It sits alongside `expose` (public) and `remote` as a kind of RPC rather than a separate concept — a step is invoked by name exactly as an RPC is, which is why a run records the step function in its `rpcName`. What makes it its own kind is that it is never network-callable: a step may drive a browser or assert against fixtures." }, "scenario": { "type": "boolean", "description": "The function behind a `pikkuScenario(...)` — a scenario's own body, as opposed to the steps it calls. Marked for the same reason as `scenarioStep`: a scenario is only ever run by `pikku scenario run`, so it has to be held back from the app bootstrap and from every deployed unit." }, "mcp": { "type": "boolean" }, "readonly": { "type": "boolean" }, "deploy": { "type": "string", "enum": ["serverless", "server", "auto"] }, "sessionless": { "type": "boolean" }, "workflowQueued": { "type": "boolean", "description": "When true, workflow steps calling this function are dispatched via the queue. No queue service configured is a hard error." }, "workflowRetries": { "type": "number", "description": "Retry count when this function is used as a workflow step." }, "workflowTimeout": { "type": "string", "description": "Timeout when this function is used as a workflow step (e.g. '30s', '5m')." }, "scenarioStepBrowser": { "type": "boolean", "description": "Scenario steps only: this step drives a browser, so the runner must provision one and an actor is mandatory." }, "scenarioStepTemplate": { "type": "string", "description": "Scenario steps only: the prose a reporter renders, with `{placeholders}` filled from the step's recorded input." }, "version": { "type": "number" }, "approvalRequired": { "type": "boolean" }, "approvalDescription": { "type": "string" }, "implementationHash": { "type": "string" }, "contractHash": { "type": "string" }, "inputHash": { "type": "string" }, "outputHash": { "type": "string" } }, "required": ["inputSchemaName", "outputSchemaName", "pikkuFuncId"] }, "FunctionServicesMeta": { "type": "object", "properties": { "optimized": { "type": "boolean" }, "services": { "type": "array", "items": { "type": "string" } } }, "required": ["optimized", "services"], "additionalProperties": false }, "FunctionWiresMeta": { "type": "object", "properties": { "optimized": { "type": "boolean" }, "wires": { "type": "array", "items": { "type": "string" } } }, "required": ["optimized", "wires"], "additionalProperties": false }, "MiddlewareMetadata": { "anyOf": [{ "type": "object", "properties": { "type": { "type": "string", "const": "http" }, "route": { "type": "string" } }, "required": ["type", "route"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "tag" }, "tag": { "type": "string" } }, "required": ["type", "tag"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "wire" }, "name": { "type": "string" }, "inline": { "type": "boolean" } }, "required": ["type", "name"], "additionalProperties": false }], "description": "Metadata for middleware at any level\n- type: 'http' = HTTP route middleware group (references httpGroup in pikkuState)\n- type: 'tag' = Tag-based middleware group (references tagGroup in pikkuState)\n- type: 'wire' = Wire-level individual middleware" }, "PermissionMetadata": { "type": "object", "properties": { "type": { "type": "string", "const": "wire" }, "name": { "type": "string" }, "inline": { "type": "boolean" } }, "required": ["type", "name"], "additionalProperties": false, "description": "A reference to a permission function a function declares, resolved by name. Used at filter time (e.g. listing agent tools) to run the session-only (pikkuAuth) predicates without request data. Permissions are function-scoped only — there are no wire- or tag-level permission references." }, "HTTPWiringsMeta": { "type": "object", "properties": { "post": { "type": "object", "additionalProperties": { "$ref": "#/definitions/HTTPWiringMeta" } }, "get": { "type": "object", "additionalProperties": { "$ref": "#/definitions/HTTPWiringMeta" } }, "delete": { "type": "object", "additionalProperties": { "$ref": "#/definitions/HTTPWiringMeta" } }, "patch": { "type": "object", "additionalProperties": { "$ref": "#/definitions/HTTPWiringMeta" } }, "head": { "type": "object", "additionalProperties": { "$ref": "#/definitions/HTTPWiringMeta" } }, "put": { "type": "object", "additionalProperties": { "$ref": "#/definitions/HTTPWiringMeta" } }, "options": { "type": "object", "additionalProperties": { "$ref": "#/definitions/HTTPWiringMeta" } } }, "required": ["post", "get", "delete", "patch", "head", "put", "options"], "additionalProperties": false }, "HTTPWiringMeta": { "type": "object", "additionalProperties": false, "properties": { "route": { "type": "string" }, "method": { "$ref": "#/definitions/HTTPMethod" }, "refTarget": { "type": "string" }, "params": { "type": "array", "items": { "type": "string" } }, "query": { "type": "array", "items": { "type": "string" } }, "inputTypes": { "$ref": "#/definitions/HTTPFunctionMetaInputTypes" }, "headersSchemaName": { "type": "string" }, "sse": { "type": "boolean", "const": true }, "groupBasePath": { "type": "string" }, "pikkuFuncId": { "type": "string" }, "packageName": { "type": "string" }, "title": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "summary": { "type": "string" }, "description": { "type": "string" }, "errors": { "type": "array", "items": { "type": "string" } }, "middleware": { "type": "array", "items": { "$ref": "#/definitions/MiddlewareMetadata" } }, "permissions": { "type": "array", "items": { "$ref": "#/definitions/PermissionMetadata" } } }, "required": ["method", "pikkuFuncId", "route"], "description": "Represents metadata for a set of HTTP wirings, including HTTP wiring details, methods, input/output types, and documentation." }, "HTTPMethod": { "type": "string", "enum": ["post", "get", "delete", "patch", "head", "put", "options"], "description": "Represents the HTTP methods supported for API HTTP wirings." }, "HTTPFunctionMetaInputTypes": { "type": "object", "properties": { "params": { "type": "string" }, "query": { "type": "string" }, "body": { "type": "string" } }, "additionalProperties": false, "description": "Represents the input types for HTTP wiring metadata, including parameters, query, and body types." }, "ChannelsMeta": { "type": "object", "additionalProperties": { "$ref": "#/definitions/ChannelMeta" } }, "ChannelMeta": { "type": "object", "properties": { "name": { "type": "string" }, "route": { "type": "string" }, "params": { "type": "array", "items": { "type": "string" } }, "query": { "type": "array", "items": { "type": "string" } }, "input": { "type": ["string", "null"] }, "inputTypes": { "$ref": "#/definitions/HTTPFunctionMetaInputTypes" }, "connect": { "anyOf": [{ "$ref": "#/definitions/ChannelMessageMeta" }, { "type": "null" }] }, "disconnect": { "anyOf": [{ "$ref": "#/definitions/ChannelMessageMeta" }, { "type": "null" }] }, "message": { "anyOf": [{ "$ref": "#/definitions/ChannelMessageMeta" }, { "type": "null" }] }, "messageWirings": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "$ref": "#/definitions/ChannelMessageMeta" } } }, "binary": { "type": ["boolean", "null"] }, "summary": { "type": "string" }, "description": { "type": "string" }, "errors": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "middleware": { "type": "array", "items": { "$ref": "#/definitions/MiddlewareMetadata" } }, "channelMiddleware": { "type": "array", "items": { "$ref": "#/definitions/MiddlewareMetadata" } } }, "required": ["name", "route", "input", "connect", "disconnect", "message", "messageWirings"], "additionalProperties": false }, "ChannelMessageMeta": { "type": "object", "properties": { "pikkuFuncId": { "type": "string" }, "packageName": { "type": "string" }, "summary": { "type": "string" }, "description": { "type": "string" }, "errors": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "middleware": { "type": "array", "items": { "$ref": "#/definitions/MiddlewareMetadata" } } }, "required": ["pikkuFuncId"], "additionalProperties": false }, "CLIProgramMeta": { "type": "object", "properties": { "program": { "type": "string" }, "commands": { "type": "object", "additionalProperties": { "$ref": "#/definitions/CLICommandMeta" } }, "options": { "type": "object", "additionalProperties": { "$ref": "#/definitions/CLIOption" } }, "defaultRenderName": { "type": "string" } }, "required": ["program", "commands", "options"], "additionalProperties": false, "description": "CLI metadata collection (per program)" }, "CLICommandMeta": { "type": "object", "properties": { "parameters": { "type": "string" }, "pikkuFuncId": { "type": "string" }, "packageName": { "type": "string" }, "positionals": { "type": "array", "items": { "$ref": "#/definitions/CLIPositional" } }, "options": { "type": "object", "additionalProperties": { "$ref": "#/definitions/CLIOption" } }, "renderName": { "type": "string" }, "summary": { "type": "string" }, "description": { "type": "string" }, "errors": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "subcommands": { "type": "object", "additionalProperties": { "$ref": "#/definitions/CLICommandMeta" } }, "middleware": { "type": "array", "items": { "$ref": "#/definitions/MiddlewareMetadata" } }, "isDefault": { "type": "boolean" } }, "required": ["pikkuFuncId", "positionals", "options"], "additionalProperties": false, "description": "CLI command metadata for runtime" }, "CLIPositional": { "type": "object", "properties": { "name": { "type": "string" }, "required": { "type": "boolean" }, "variadic": { "type": "boolean" } }, "required": ["name", "required"], "additionalProperties": false, "description": "Positional argument definition" }, "CLIOption": { "type": "object", "properties": { "description": { "type": "string" }, "short": { "type": "string" }, "default": {}, "choices": { "type": "array", "items": {} }, "array": { "type": "boolean" }, "required": { "type": "boolean" } }, "required": ["description"], "additionalProperties": false, "description": "CLI option definition" }, "McpMeta": { "type": "object", "properties": { "toolsMeta": { "$ref": "#/definitions/MCPToolMeta" }, "resourcesMeta": { "$ref": "#/definitions/MCPResourceMeta" }, "promptsMeta": { "$ref": "#/definitions/MCPPromptMeta" } }, "required": ["toolsMeta", "resourcesMeta", "promptsMeta"], "additionalProperties": false }, "MCPToolMeta": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": false, "properties": { "pikkuFuncId": { "type": "string" }, "inputSchema": { "type": ["string", "null"] }, "outputSchema": { "type": ["string", "null"] }, "middleware": { "type": "array", "items": { "$ref": "#/definitions/MiddlewareMetadata" } }, "name": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "summary": { "type": "string" }, "errors": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "streaming": { "type": "boolean" } }, "required": ["inputSchema", "name", "outputSchema", "pikkuFuncId"] }, "description": "Represents metadata for MCP tools, including name, description, and documentation." }, "MCPResourceMeta": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": false, "properties": { "pikkuFuncId": { "type": "string" }, "inputSchema": { "type": ["string", "null"] }, "outputSchema": { "type": ["string", "null"] }, "middleware": { "type": "array", "items": { "$ref": "#/definitions/MiddlewareMetadata" } }, "uri": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "summary": { "type": "string" }, "errors": { "type": "array", "items": { "type": "string" } }, "mimeType": { "type": "string" }, "size": { "type": "number" }, "streaming": { "type": "boolean" }, "tags": { "type": "array", "items": { "type": "string" } } }, "required": ["description", "inputSchema", "outputSchema", "pikkuFuncId", "title", "uri"] }, "description": "Represents metadata for MCP resources, including name, description, and documentation." }, "MCPPromptMeta": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": false, "properties": { "pikkuFuncId": { "type": "string" }, "inputSchema": { "type": ["string", "null"] }, "outputSchema": { "type": ["string", "null"] }, "arguments": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "required": { "type": "boolean" } }, "required": ["name", "description", "required"], "additionalProperties": false } }, "middleware": { "type": "array", "items": { "$ref": "#/definitions/MiddlewareMetadata" } }, "name": { "type": "string" }, "description": { "type": "string" }, "summary": { "type": "string" }, "errors": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } } }, "required": ["arguments", "description", "inputSchema", "name", "outputSchema", "pikkuFuncId"] }, "description": "Represents metadata for MCP prompts, including name, description, and arguments." } } }
1	+ { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "displayName": { "type": "string" }, "version": { "type": "string" }, "description": { "type": "string" }, "author": { "type": "string" }, "repository": { "type": "string" }, "license": { "type": "string" }, "readme": { "type": "string" }, "icon": { "type": "string" }, "publishedAt": { "type": "string" }, "updatedAt": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "categories": { "type": "array", "items": { "type": "string" } }, "functions": { "$ref": "#/definitions/FunctionsMeta" }, "agents": { "type": "object", "additionalProperties": {} }, "secrets": { "type": "object", "additionalProperties": {} }, "credentials": { "type": "object", "additionalProperties": {}, "description": "OAuth2 + wire credentials the addon declares (from its own `credentials/pikku-credentials-meta.gen.json`). Entries with an `oauth2` field are OAuth integrations to connect; the rest are wire credentials." }, "variables": { "type": "object", "additionalProperties": {} }, "httpRoutes": { "$ref": "#/definitions/HTTPWiringsMeta" }, "channels": { "$ref": "#/definitions/ChannelsMeta" }, "cli": { "type": "object", "additionalProperties": { "$ref": "#/definitions/CLIProgramMeta" } }, "mcp": { "anyOf": [{ "$ref": "#/definitions/McpMeta" }, { "type": "null" }] }, "schemas": { "type": "object", "additionalProperties": {} } }, "required": ["id", "name", "displayName", "version", "description", "author", "publishedAt", "updatedAt", "tags", "categories", "functions", "agents", "secrets", "credentials", "variables", "httpRoutes", "channels", "cli", "mcp", "schemas"], "additionalProperties": false, "definitions": { "FunctionsMeta": { "type": "object", "additionalProperties": { "$ref": "#/definitions/FunctionMeta" } }, "FunctionMeta": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string" }, "functionType": { "type": "string", "enum": ["user", "inline", "helper", "remote"], "description": "`remote`: a contract with no local body, answered by a connected client." }, "funcWrapper": { "type": "string" }, "services": { "$ref": "#/definitions/FunctionServicesMeta" }, "wires": { "$ref": "#/definitions/FunctionWiresMeta" }, "inputs": { "anyOf": [{ "type": "array", "items": { "type": "string" } }, { "type": "null" }] }, "outputs": { "anyOf": [{ "type": "array", "items": { "type": "string" } }, { "type": "null" }] }, "middleware": { "type": "array", "items": { "$ref": "#/definitions/MiddlewareMetadata" } }, "permissions": { "type": "array", "items": { "$ref": "#/definitions/PermissionMetadata" } }, "isDirectFunction": { "type": "boolean" }, "sourceFile": { "type": "string" }, "exportedName": { "type": "string" }, "bodySourceFile": { "type": "string", "description": "File containing the handler body when it differs from sourceFile (imported handlers)" }, "bodyStart": { "type": "number", "description": "1-indexed first line of the handler body (verbose meta; coverage mapping)" }, "bodyEnd": { "type": "number", "description": "1-indexed last line of the handler body (verbose meta; coverage mapping)" }, "pikkuFuncId": { "type": "string" }, "packageName": { "type": "string" }, "title": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "summary": { "type": "string" }, "description": { "type": "string" }, "errors": { "type": "array", "items": { "type": "string" } }, "inputSchemaName": { "type": ["string", "null"] }, "outputSchemaName": { "type": ["string", "null"] }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "Scopes the session must hold to run this function. All are required (AND)." }, "expose": { "type": "boolean" }, "auth": { "type": "boolean", "description": "A sessionless function's own `auth: true`. `sessionless` carries the baseline — a `pikkuFunc` always requires a session — and this carries the tightening a `pikkuSessionlessFunc` applies to itself. Both are needed to know whether a function is gated without running it." }, "selfAuthenticated": { "type": "boolean", "description": "The author's declaration that this function authorizes callers in its own body. Carries no runtime effect — it records a gate codegen cannot see, so an audit is not left to guess whether a sessionless function is open." }, "remote": { "type": "boolean" }, "scenarioStep": { "type": "boolean", "description": "A step RPC: invoked by name only from a scenario run and refused everywhere else, so it is never network-callable." }, "scenario": { "type": "boolean", "description": "The body of a `pikkuScenario(...)`. Only ever run by `pikku scenario run`, so it is held back from the app bootstrap and from every deployed unit." }, "mcp": { "type": "boolean" }, "readonly": { "type": "boolean" }, "deploy": { "type": "string", "enum": ["serverless", "server", "auto"] }, "sessionless": { "type": "boolean" }, "workflowQueued": { "type": "boolean", "description": "When true, workflow steps calling this function are dispatched via the queue. No queue service configured is a hard error." }, "workflowRetries": { "type": "number", "description": "Retry count when this function is used as a workflow step." }, "workflowTimeout": { "type": "string", "description": "Timeout when this function is used as a workflow step (e.g. '30s', '5m')." }, "scenarioStepSurfaces": { "type": "array", "items": { "$ref": "#/definitions/ScenarioSurface" }, "description": "Scenario steps only: which surfaces this step declares a binding for.\n\nThe reporter derives coverage from this — a `then` with no binding for the surface the run targeted was never actually witnessed there, which is a gap worth counting rather than excusing." }, "scenarioStepKind": { "$ref": "#/definitions/ScenarioStepKind", "description": "Scenario steps only: who acts. Absent means `persona` — the ordinary step, and the only kind that existed before the other two.\n\nA `platform` or `addon` step is the app or a third-party system acting, and it must never reach a virtual user's catalogue. That is not tidiness: a virtual user that can invoke \"Stripe's webhook arrives\" can forge its own payment success, and every finding downstream of that is worthless." }, "scenarioStepAddon": { "type": "string", "description": "Addon steps only: the addon whose system acts — `wireAddon`'s `name`." }, "scenarioStepTemplate": { "type": "string", "description": "Scenario steps only: the prose a reporter renders, with `{placeholders}` filled from the step's recorded input." }, "secretBroker": { "type": "boolean", "description": "Keeps the full `SecretService`. Set by the inspector, read by the runner." }, "version": { "type": "number" }, "approvalRequired": { "type": "boolean" }, "approvalDescription": { "type": "string" }, "implementationHash": { "type": "string" }, "contractHash": { "type": "string" }, "inputHash": { "type": "string" }, "outputHash": { "type": "string" } }, "required": ["inputSchemaName", "outputSchemaName", "pikkuFuncId"] }, "FunctionServicesMeta": { "type": "object", "properties": { "optimized": { "type": "boolean" }, "services": { "type": "array", "items": { "type": "string" } } }, "required": ["optimized", "services"], "additionalProperties": false }, "FunctionWiresMeta": { "type": "object", "properties": { "optimized": { "type": "boolean" }, "wires": { "type": "array", "items": { "type": "string" } } }, "required": ["optimized", "wires"], "additionalProperties": false }, "MiddlewareMetadata": { "anyOf": [{ "type": "object", "properties": { "type": { "type": "string", "const": "http" }, "route": { "type": "string" } }, "required": ["type", "route"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "tag" }, "tag": { "type": "string" } }, "required": ["type", "tag"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "wire" }, "name": { "type": "string" }, "inline": { "type": "boolean" } }, "required": ["type", "name"], "additionalProperties": false }] }, "PermissionMetadata": { "type": "object", "properties": { "type": { "type": "string", "const": "wire" }, "name": { "type": "string" }, "inline": { "type": "boolean" } }, "required": ["type", "name"], "additionalProperties": false, "description": "A reference to a permission function, resolved by name. Function-scoped only: there are no wire- or tag-level permission references." }, "ScenarioSurface": { "type": "string", "enum": ["browser", "cli", "default"], "description": "How an actor drives the system for one step.\n\nA step declares one implementation per surface it supports, and the runner picks between them — so the same ladder can run through a real browser, over the websocket, or entirely server-side.\n\n`default` is the floor: it is what every other surface falls back to, so it can never itself fall back." }, "ScenarioStepKind": { "type": "string", "enum": ["persona", "platform", "addon"], "description": "Who acts in a step.\n\n`persona` is a person driving the system through one of its surfaces — the ordinary `pikkuScenarioStep`. `platform` is the app acting on itself (\"the platform has expired the trial\"), and `addon` is a third-party system acting on it (\"Stripe's webhook arrives\"), contributed by the addon that wraps that service.\n\nThe three are separate declarations rather than a field on one, so the inspector verifies a step's kind by which function was called rather than by trusting a string literal — and so an addon package exports only addon steps, which is checkable." }, "HTTPWiringsMeta": { "type": "object", "properties": { "post": { "type": "object", "additionalProperties": { "$ref": "#/definitions/HTTPWiringMeta" } }, "get": { "type": "object", "additionalProperties": { "$ref": "#/definitions/HTTPWiringMeta" } }, "delete": { "type": "object", "additionalProperties": { "$ref": "#/definitions/HTTPWiringMeta" } }, "patch": { "type": "object", "additionalProperties": { "$ref": "#/definitions/HTTPWiringMeta" } }, "head": { "type": "object", "additionalProperties": { "$ref": "#/definitions/HTTPWiringMeta" } }, "put": { "type": "object", "additionalProperties": { "$ref": "#/definitions/HTTPWiringMeta" } }, "options": { "type": "object", "additionalProperties": { "$ref": "#/definitions/HTTPWiringMeta" } } }, "required": ["post", "get", "delete", "patch", "head", "put", "options"], "additionalProperties": false }, "HTTPWiringMeta": { "type": "object", "additionalProperties": false, "properties": { "route": { "type": "string" }, "method": { "$ref": "#/definitions/HTTPMethod" }, "auth": { "type": "boolean", "description": "The route's own `auth`, or the group's if the route did not set one." }, "requiresSession": { "type": "boolean", "description": "Whether reaching this route requires a session, resolved at codegen time across every layer that can demand one: the function's `sessionless`, its own `auth`, this route's `auth`, and the auth flag of the addon the function belongs to. Answering \"which routes are open?\" used to mean joining four separate places and knowing which of them wins; getting that join wrong reads an open route as a closed one." }, "refTarget": { "type": "string" }, "params": { "type": "array", "items": { "type": "string" } }, "query": { "type": "array", "items": { "type": "string" } }, "inputTypes": { "$ref": "#/definitions/HTTPFunctionMetaInputTypes" }, "headersSchemaName": { "type": "string" }, "sse": { "type": "boolean", "const": true }, "groupBasePath": { "type": "string" }, "pikkuFuncId": { "type": "string" }, "packageName": { "type": "string" }, "title": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "summary": { "type": "string" }, "description": { "type": "string" }, "errors": { "type": "array", "items": { "type": "string" } }, "middleware": { "type": "array", "items": { "$ref": "#/definitions/MiddlewareMetadata" } }, "permissions": { "type": "array", "items": { "$ref": "#/definitions/PermissionMetadata" } } }, "required": ["method", "pikkuFuncId", "route"] }, "HTTPMethod": { "type": "string", "enum": ["post", "get", "delete", "patch", "head", "put", "options"] }, "HTTPFunctionMetaInputTypes": { "type": "object", "properties": { "params": { "type": "string" }, "query": { "type": "string" }, "body": { "type": "string" } }, "additionalProperties": false }, "ChannelsMeta": { "type": "object", "additionalProperties": { "$ref": "#/definitions/ChannelMeta" } }, "ChannelMeta": { "type": "object", "properties": { "name": { "type": "string" }, "route": { "type": "string" }, "params": { "type": "array", "items": { "type": "string" } }, "query": { "type": "array", "items": { "type": "string" } }, "input": { "type": ["string", "null"] }, "inputTypes": { "$ref": "#/definitions/HTTPFunctionMetaInputTypes" }, "connect": { "anyOf": [{ "$ref": "#/definitions/ChannelMessageMeta" }, { "type": "null" }] }, "disconnect": { "anyOf": [{ "$ref": "#/definitions/ChannelMessageMeta" }, { "type": "null" }] }, "message": { "anyOf": [{ "$ref": "#/definitions/ChannelMessageMeta" }, { "type": "null" }] }, "messageWirings": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "$ref": "#/definitions/ChannelMessageMeta" } } }, "binary": { "type": ["boolean", "null"] }, "summary": { "type": "string" }, "description": { "type": "string" }, "errors": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "middleware": { "type": "array", "items": { "$ref": "#/definitions/MiddlewareMetadata" } }, "channelMiddleware": { "type": "array", "items": { "$ref": "#/definitions/MiddlewareMetadata" } } }, "required": ["name", "route", "input", "connect", "disconnect", "message", "messageWirings"], "additionalProperties": false }, "ChannelMessageMeta": { "type": "object", "properties": { "pikkuFuncId": { "type": "string" }, "packageName": { "type": "string" }, "summary": { "type": "string" }, "description": { "type": "string" }, "errors": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "middleware": { "type": "array", "items": { "$ref": "#/definitions/MiddlewareMetadata" } } }, "required": ["pikkuFuncId"], "additionalProperties": false }, "CLIProgramMeta": { "type": "object", "properties": { "program": { "type": "string" }, "commands": { "type": "object", "additionalProperties": { "$ref": "#/definitions/CLICommandMeta" } }, "options": { "type": "object", "additionalProperties": { "$ref": "#/definitions/CLIOption" } }, "defaultRenderName": { "type": "string" }, "auth": { "type": "boolean", "description": "Whether the channel serving this program over a websocket requires a session. Only meaningful for the generated channel backend — a locally executed CLI has no connection to authenticate." } }, "required": ["program", "commands", "options"], "additionalProperties": false, "description": "CLI metadata collection (per program)" }, "CLICommandMeta": { "type": "object", "properties": { "parameters": { "type": "string" }, "pikkuFuncId": { "type": "string" }, "packageName": { "type": "string" }, "positionals": { "type": "array", "items": { "$ref": "#/definitions/CLIPositional" } }, "options": { "type": "object", "additionalProperties": { "$ref": "#/definitions/CLIOption" } }, "renderName": { "type": "string" }, "summary": { "type": "string" }, "description": { "type": "string" }, "errors": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "subcommands": { "type": "object", "additionalProperties": { "$ref": "#/definitions/CLICommandMeta" } }, "middleware": { "type": "array", "items": { "$ref": "#/definitions/MiddlewareMetadata" } }, "isDefault": { "type": "boolean" } }, "required": ["pikkuFuncId", "positionals", "options"], "additionalProperties": false, "description": "CLI command metadata for runtime" }, "CLIPositional": { "type": "object", "properties": { "name": { "type": "string" }, "required": { "type": "boolean" }, "variadic": { "type": "boolean" } }, "required": ["name", "required"], "additionalProperties": false, "description": "Positional argument definition" }, "CLIOption": { "type": "object", "properties": { "description": { "type": "string" }, "short": { "type": "string" }, "default": {}, "choices": { "type": "array", "items": {} }, "array": { "type": "boolean" }, "required": { "type": "boolean" } }, "required": ["description"], "additionalProperties": false, "description": "CLI option definition" }, "McpMeta": { "type": "object", "properties": { "toolsMeta": { "$ref": "#/definitions/MCPToolMeta" }, "resourcesMeta": { "$ref": "#/definitions/MCPResourceMeta" }, "promptsMeta": { "$ref": "#/definitions/MCPPromptMeta" } }, "required": ["toolsMeta", "resourcesMeta", "promptsMeta"], "additionalProperties": false }, "MCPToolMeta": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": false, "properties": { "pikkuFuncId": { "type": "string" }, "inputSchema": { "type": ["string", "null"] }, "outputSchema": { "type": ["string", "null"] }, "middleware": { "type": "array", "items": { "$ref": "#/definitions/MiddlewareMetadata" } }, "name": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "summary": { "type": "string" }, "errors": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "streaming": { "type": "boolean" } }, "required": ["inputSchema", "name", "outputSchema", "pikkuFuncId"] } }, "MCPResourceMeta": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": false, "properties": { "pikkuFuncId": { "type": "string" }, "inputSchema": { "type": ["string", "null"] }, "outputSchema": { "type": ["string", "null"] }, "middleware": { "type": "array", "items": { "$ref": "#/definitions/MiddlewareMetadata" } }, "uri": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "summary": { "type": "string" }, "errors": { "type": "array", "items": { "type": "string" } }, "mimeType": { "type": "string" }, "size": { "type": "number" }, "streaming": { "type": "boolean" }, "tags": { "type": "array", "items": { "type": "string" } } }, "required": ["description", "inputSchema", "outputSchema", "pikkuFuncId", "title", "uri"] } }, "MCPPromptMeta": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": false, "properties": { "pikkuFuncId": { "type": "string" }, "inputSchema": { "type": ["string", "null"] }, "outputSchema": { "type": ["string", "null"] }, "arguments": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "required": { "type": "boolean" } }, "required": ["name", "description", "required"], "additionalProperties": false } }, "middleware": { "type": "array", "items": { "$ref": "#/definitions/MiddlewareMetadata" } }, "name": { "type": "string" }, "description": { "type": "string" }, "summary": { "type": "string" }, "errors": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } } }, "required": ["arguments", "description", "inputSchema", "name", "outputSchema", "pikkuFuncId"] } } } }

package/dist/.pikku/schemas/schemas/AllMeta.schema.json CHANGED Viewed

	@@ -1 +1 @@
1	- { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "functions": { "type": "array", "items": { "$ref": "#/definitions/FunctionMeta" } }, "httpMeta": { "type": "array", "items": { "$ref": "#/definitions/HttpRouteMeta" } }, "cliMeta": { "type": "array", "items": { "$ref": "#/definitions/CliProgramMeta" } }, "cliRenderers": { "type": "object", "additionalProperties": { "$ref": "#/definitions/CliRendererMeta" } }, "channelsMeta": { "type": "object", "additionalProperties": { "$ref": "#/definitions/ChannelMeta" } }, "queueMeta": { "type": "object", "additionalProperties": { "$ref": "#/definitions/QueueWorkerMeta" } }, "schedulerMeta": { "type": "object", "additionalProperties": { "$ref": "#/definitions/SchedulerTaskMeta" } }, "rpcMeta": { "type": "object", "additionalProperties": { "$ref": "#/definitions/RpcMeta" } }, "mcpMeta": { "type": "array", "items": { "$ref": "#/definitions/McpItemMeta" } }, "gatewayMeta": { "type": "array", "items": { "$ref": "#/definitions/GatewayItemMeta" } }, "workflows": { "$ref": "#/definitions/WorkflowsMeta" }, "scenarioActors": { "type": "object", "additionalProperties": { "type": "object", "properties": { "email": { "type": "string" }, "name": { "type": "string" }, "jobTitle": { "type": "string" }, "personality": { "type": "string" } }, "required": ["email"], "additionalProperties": false } }, "features": { "$ref": "#/definitions/FeaturesMeta" }, "triggerMeta": { "type": "object", "additionalProperties": { "$ref": "#/definitions/TriggerMeta" } }, "triggerSourceMeta": { "type": "object", "additionalProperties": { "$ref": "#/definitions/TriggerSourceMeta" } }, "middlewareGroupsMeta": { "$ref": "#/definitions/MiddlewareGroupsMeta" }, "permissionsGroupsMeta": { "$ref": "#/definitions/PermissionsGroupsMeta" }, "agentsMeta": { "$ref": "#/definitions/AgentsMeta" }, "emailsMeta": { "$ref": "#/definitions/EmailsMeta" }, "secretsMeta": { "type": "object", "additionalProperties": {} }, "credentialsMeta": { "type": "object", "additionalProperties": {} }, "variablesMeta": { "type": "object", "additionalProperties": {} }, "functionUsedBy": { "type": "object", "additionalProperties": { "$ref": "#/definitions/FunctionUsedBy" } }, "counts": { "$ref": "#/definitions/MetaCounts" } }, "required": ["agentsMeta", "channelsMeta", "cliMeta", "cliRenderers", "counts", "credentialsMeta", "emailsMeta", "features", "functionUsedBy", "functions", "gatewayMeta", "httpMeta", "mcpMeta", "middlewareGroupsMeta", "permissionsGroupsMeta", "queueMeta", "rpcMeta", "scenarioActors", "schedulerMeta", "secretsMeta", "triggerMeta", "triggerSourceMeta", "variablesMeta", "workflows"], "additionalProperties": false, "definitions": { "FunctionMeta": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string" }, "functionType": { "type": "string", "enum": ["user", "inline", "helper"] }, "funcWrapper": { "type": "string" }, "services": { "$ref": "#/definitions/FunctionServicesMeta" }, "wires": { "$ref": "#/definitions/FunctionWiresMeta" }, "inputs": { "anyOf": [{ "type": "array", "items": { "type": "string" } }, { "type": "null" }] }, "outputs": { "anyOf": [{ "type": "array", "items": { "type": "string" } }, { "type": "null" }] }, "middleware": { "type": "array", "items": { "$ref": "#/definitions/MiddlewareMetadata" } }, "permissions": { "type": "array", "items": { "$ref": "#/definitions/PermissionMetadata" } }, "isDirectFunction": { "type": "boolean" }, "sourceFile": { "type": "string" }, "exportedName": { "type": "string" }, "bodySourceFile": { "type": "string", "description": "File containing the handler body when it differs from sourceFile (imported handlers)" }, "bodyStart": { "type": "number", "description": "1-indexed first line of the handler body (verbose meta; coverage mapping)" }, "bodyEnd": { "type": "number", "description": "1-indexed last line of the handler body (verbose meta; coverage mapping)" }, "pikkuFuncId": { "type": "string" }, "packageName": { "type": "string" }, "title": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "summary": { "type": "string" }, "description": { "type": "string" }, "errors": { "type": "array", "items": { "type": "string" } }, "inputSchemaName": { "type": ["string", "null"] }, "outputSchemaName": { "type": ["string", "null"] }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "Scopes the session must hold to run this function. All are required (AND)." }, "expose": { "type": "boolean" }, "remote": { "type": "boolean" }, "scenarioStep": { "type": "boolean", "description": "A step RPC: a name dispatched by a scenario run and refused everywhere else. It sits alongside `expose` (public) and `remote` as a kind of RPC rather than a separate concept — a step is invoked by name exactly as an RPC is, which is why a run records the step function in its `rpcName`. What makes it its own kind is that it is never network-callable: a step may drive a browser or assert against fixtures." }, "scenario": { "type": "boolean", "description": "The function behind a `pikkuScenario(...)` — a scenario's own body, as opposed to the steps it calls. Marked for the same reason as `scenarioStep`: a scenario is only ever run by `pikku scenario run`, so it has to be held back from the app bootstrap and from every deployed unit." }, "mcp": { "type": "boolean" }, "readonly": { "type": "boolean" }, "deploy": { "type": "string", "enum": ["serverless", "server", "auto"] }, "sessionless": { "type": "boolean" }, "workflowQueued": { "type": "boolean", "description": "When true, workflow steps calling this function are dispatched via the queue. No queue service configured is a hard error." }, "workflowRetries": { "type": "number", "description": "Retry count when this function is used as a workflow step." }, "workflowTimeout": { "type": "string", "description": "Timeout when this function is used as a workflow step (e.g. '30s', '5m')." }, "scenarioStepBrowser": { "type": "boolean", "description": "Scenario steps only: this step drives a browser, so the runner must provision one and an actor is mandatory." }, "scenarioStepTemplate": { "type": "string", "description": "Scenario steps only: the prose a reporter renders, with `{placeholders}` filled from the step's recorded input." }, "version": { "type": "number" }, "approvalRequired": { "type": "boolean" }, "approvalDescription": { "type": "string" }, "implementationHash": { "type": "string" }, "contractHash": { "type": "string" }, "inputHash": { "type": "string" }, "outputHash": { "type": "string" } }, "required": ["inputSchemaName", "outputSchemaName", "pikkuFuncId"] }, "FunctionServicesMeta": { "type": "object", "properties": { "optimized": { "type": "boolean" }, "services": { "type": "array", "items": { "type": "string" } } }, "required": ["optimized", "services"], "additionalProperties": false }, "FunctionWiresMeta": { "type": "object", "properties": { "optimized": { "type": "boolean" }, "wires": { "type": "array", "items": { "type": "string" } } }, "required": ["optimized", "wires"], "additionalProperties": false }, "MiddlewareMetadata": { "anyOf": [{ "type": "object", "properties": { "type": { "type": "string", "const": "http" }, "route": { "type": "string" } }, "required": ["type", "route"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "tag" }, "tag": { "type": "string" } }, "required": ["type", "tag"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "wire" }, "name": { "type": "string" }, "inline": { "type": "boolean" } }, "required": ["type", "name"], "additionalProperties": false }], "description": "Metadata for middleware at any level\n- type: 'http' = HTTP route middleware group (references httpGroup in pikkuState)\n- type: 'tag' = Tag-based middleware group (references tagGroup in pikkuState)\n- type: 'wire' = Wire-level individual middleware" }, "PermissionMetadata": { "type": "object", "properties": { "type": { "type": "string", "const": "wire" }, "name": { "type": "string" }, "inline": { "type": "boolean" } }, "required": ["type", "name"], "additionalProperties": false, "description": "A reference to a permission function a function declares, resolved by name. Used at filter time (e.g. listing agent tools) to run the session-only (pikkuAuth) predicates without request data. Permissions are function-scoped only — there are no wire- or tag-level permission references." }, "HttpRouteMeta": { "type": "object", "properties": { "pikkuFuncId": { "type": "string" }, "route": { "type": "string" }, "method": { "type": "string" }, "params": { "type": "array", "items": { "type": "string" } }, "query": { "type": "array", "items": { "type": "string" } }, "summary": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "errors": { "type": "array", "items": { "type": "string" } }, "auth": { "type": "boolean" }, "sse": { "type": "boolean" }, "middleware": { "type": "array", "items": { "$ref": "#/definitions/MiddlewareMetadata" } }, "permissions": { "type": "array", "items": { "$ref": "#/definitions/PermissionMetadata" } }, "inputSchemaName": { "type": "string" }, "outputSchemaName": { "type": "string" } }, "required": ["pikkuFuncId", "route", "method"], "additionalProperties": false }, "CliProgramMeta": { "type": "object", "properties": { "wireId": { "type": "string" }, "program": { "type": "string" }, "description": { "type": "string" }, "commands": { "type": "object", "additionalProperties": { "$ref": "#/definitions/CliCommandMeta" } }, "options": { "type": "object", "additionalProperties": { "$ref": "#/definitions/CliOptionMeta" } }, "defaultRenderName": { "type": "string" } }, "required": ["wireId", "program", "commands", "options"], "additionalProperties": false }, "CliCommandMeta": { "type": "object", "properties": { "pikkuFuncId": { "type": "string" }, "description": { "type": "string" }, "summary": { "type": "string" }, "parameters": { "type": "string" }, "positionals": { "type": "array", "items": { "$ref": "#/definitions/CliPositionalMeta" } }, "options": { "type": "object", "additionalProperties": { "$ref": "#/definitions/CliOptionMeta" } }, "renderName": { "type": "string" }, "subcommands": { "type": "object", "additionalProperties": { "$ref": "#/definitions/CliCommandMeta" } }, "isDefault": { "type": "boolean" } }, "required": ["pikkuFuncId", "positionals", "options"], "additionalProperties": false }, "CliPositionalMeta": { "type": "object", "properties": { "name": { "type": "string" }, "required": { "type": "boolean" }, "variadic": { "type": "boolean" } }, "required": ["name", "required"], "additionalProperties": false }, "CliOptionMeta": { "type": "object", "properties": { "description": { "type": "string" }, "short": { "type": "string" }, "default": {}, "choices": { "type": "array", "items": {} }, "array": { "type": "boolean" }, "required": { "type": "boolean" } }, "required": ["description"], "additionalProperties": false }, "CliRendererMeta": { "type": "object", "properties": { "name": { "type": "string" }, "exportedName": { "type": "string" }, "filePath": { "type": "string" }, "services": { "type": "object", "properties": { "optimized": { "type": "boolean" }, "services": { "type": "array", "items": { "type": "string" } } }, "required": ["optimized", "services"], "additionalProperties": false } }, "required": ["name", "filePath", "services"], "additionalProperties": false }, "ChannelMeta": { "type": "object", "properties": { "name": { "type": "string" }, "route": { "type": "string" }, "params": { "type": "array", "items": { "type": "string" } }, "query": { "type": "array", "items": { "type": "string" } }, "input": { "type": ["string", "null"] }, "connect": { "anyOf": [{ "$ref": "#/definitions/ChannelMessageMeta" }, { "type": "null" }] }, "disconnect": { "anyOf": [{ "$ref": "#/definitions/ChannelMessageMeta" }, { "type": "null" }] }, "message": { "anyOf": [{ "$ref": "#/definitions/ChannelMessageMeta" }, { "type": "null" }] }, "messageWirings": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "$ref": "#/definitions/ChannelMessageMeta" } } }, "summary": { "type": "string" }, "description": { "type": "string" }, "errors": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "middleware": { "type": "array", "items": { "$ref": "#/definitions/MiddlewareMetadata" } }, "permissions": { "type": "array", "items": { "$ref": "#/definitions/PermissionMetadata" } } }, "required": ["name", "route", "input", "connect", "disconnect", "message", "messageWirings"], "additionalProperties": false }, "ChannelMessageMeta": { "type": "object", "properties": { "pikkuFuncId": { "type": "string" }, "summary": { "type": "string" }, "description": { "type": "string" }, "errors": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "middleware": { "type": "array", "items": { "$ref": "#/definitions/MiddlewareMetadata" } }, "permissions": { "type": "array", "items": { "$ref": "#/definitions/PermissionMetadata" } } }, "required": ["pikkuFuncId"], "additionalProperties": false }, "QueueWorkerMeta": { "type": "object", "properties": { "pikkuFuncId": { "type": "string" }, "queueName": { "type": "string" }, "summary": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "middleware": { "type": "array", "items": { "$ref": "#/definitions/MiddlewareMetadata" } }, "permissions": { "type": "array", "items": { "$ref": "#/definitions/PermissionMetadata" } }, "config": { "type": "object", "additionalProperties": {} } }, "required": ["pikkuFuncId", "queueName"], "additionalProperties": false }, "SchedulerTaskMeta": { "type": "object", "properties": { "pikkuFuncId": { "type": "string" }, "name": { "type": "string" }, "schedule": { "type": "string" }, "summary": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "middleware": { "type": "array", "items": { "$ref": "#/definitions/MiddlewareMetadata" } }, "permissions": { "type": "array", "items": { "$ref": "#/definitions/PermissionMetadata" } } }, "required": ["pikkuFuncId", "name", "schedule"], "additionalProperties": false }, "RpcMeta": { "type": "object", "properties": { "pikkuFuncId": { "type": "string" } }, "required": ["pikkuFuncId"], "additionalProperties": false }, "McpItemMeta": { "type": "object", "properties": { "pikkuFuncId": { "type": "string" }, "method": { "type": "string", "enum": ["resource", "tool", "prompt"] }, "name": { "type": "string" }, "wireId": { "type": "string" }, "description": { "type": "string" }, "summary": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "errors": { "type": "array", "items": { "type": "string" } }, "uri": { "type": "string" }, "arguments": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "required": { "type": "boolean" } }, "required": ["name"], "additionalProperties": false } }, "middleware": { "type": "array", "items": { "$ref": "#/definitions/MiddlewareMetadata" } }, "permissions": { "type": "array", "items": { "$ref": "#/definitions/PermissionMetadata" } }, "inputSchemaName": { "type": "string" }, "outputSchemaName": { "type": "string" } }, "required": ["pikkuFuncId", "method"], "additionalProperties": false }, "GatewayItemMeta": { "type": "object", "properties": { "pikkuFuncId": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string", "enum": ["webhook", "websocket", "listener"] }, "route": { "type": "string" }, "platform": { "type": "string" }, "packageName": { "type": "string" }, "summary": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "errors": { "type": "array", "items": { "type": "string" } }, "auth": { "type": "boolean" }, "gateway": { "type": "boolean", "const": true }, "middleware": { "type": "array", "items": { "$ref": "#/definitions/MiddlewareMetadata" } }, "permissions": { "type": "array", "items": { "$ref": "#/definitions/PermissionMetadata" } } }, "required": ["pikkuFuncId", "name", "type", "gateway"], "additionalProperties": false }, "WorkflowsMeta": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string" }, "steps": { "type": "array", "items": { "$ref": "#/definitions/WorkflowStepMeta" } }, "context": { "$ref": "#/definitions/WorkflowContext" }, "dsl": { "type": "boolean" }, "expose": { "type": "boolean" }, "scenario": { "type": "boolean", "description": "True for pikkuScenario workflows (complex + actor steps)." }, "skip": { "type": "string", "description": "Why a scenario is held out of a default run. Stating the reason in code keeps the quarantine next to the scenario it applies to, rather than in a CI invocation nobody reads. Naming the scenario with `--flows` runs it regardless." }, "actors": { "type": "array", "items": { "type": "string" }, "description": "Actor names a scenario declares (personas it runs steps as)." }, "pikkuFuncId": { "type": "string" }, "packageName": { "type": "string" }, "title": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "summary": { "type": "string" }, "description": { "type": "string" }, "errors": { "type": "array", "items": { "type": "string" } }, "middleware": { "type": "array", "items": { "$ref": "#/definitions/MiddlewareMetadata" } }, "permissions": { "type": "array", "items": { "$ref": "#/definitions/PermissionMetadata" } } }, "required": ["name", "pikkuFuncId", "steps"] }, "description": "Workflows metadata for inspector/CLI (DSL step-based format)" }, "WorkflowStepMeta": { "anyOf": [{ "$ref": "#/definitions/RpcStepMeta" }, { "$ref": "#/definitions/ScenarioStepMeta" }, { "$ref": "#/definitions/BranchStepMeta" }, { "$ref": "#/definitions/ParallelGroupStepMeta" }, { "$ref": "#/definitions/FanoutStepMeta" }, { "$ref": "#/definitions/ReturnStepMeta" }, { "$ref": "#/definitions/InlineStepMeta" }, { "$ref": "#/definitions/SleepStepMeta" }, { "$ref": "#/definitions/CancelStepMeta" }, { "$ref": "#/definitions/SuspendStepMeta" }, { "$ref": "#/definitions/ApprovalStepMeta" }, { "$ref": "#/definitions/SwitchStepMeta" }, { "$ref": "#/definitions/FilterStepMeta" }, { "$ref": "#/definitions/ArrayPredicateStepMeta" }, { "$ref": "#/definitions/SetStepMeta" }], "description": "Workflow step metadata (extracted by inspector)" }, "RpcStepMeta": { "type": "object", "properties": { "type": { "type": "string", "const": "rpc", "description": "RPC form - generates queue worker" }, "stepName": { "type": "string", "description": "Cache key (stepName from workflow.do)" }, "rpcName": { "type": "string", "description": "RPC to invoke" }, "outputVar": { "type": "string", "description": "Output variable name (if assigned)" }, "inputs": { "anyOf": [{ "type": "object", "additionalProperties": { "$ref": "#/definitions/InputSource" } }, { "type": "string", "const": "passthrough" }], "description": "Input source mappings, or 'passthrough' when entire data is passed" }, "options": { "$ref": "#/definitions/WorkflowStepOptions", "description": "Step options" }, "actor": { "type": "string", "description": "Scenario actor name this step runs as ({ actor: actors.x })" }, "expectEventually": { "type": "boolean", "description": "True for workflow.expectEventually polling steps" } }, "required": ["type", "stepName", "rpcName"], "additionalProperties": false, "description": "RPC step metadata (base form)" }, "InputSource": { "anyOf": [{ "type": "object", "properties": { "from": { "type": "string", "const": "input" }, "path": { "type": "string" } }, "required": ["from", "path"], "additionalProperties": false }, { "type": "object", "properties": { "from": { "type": "string", "const": "outputVar" }, "name": { "type": "string" }, "path": { "type": "string" } }, "required": ["from", "name"], "additionalProperties": false }, { "type": "object", "properties": { "from": { "type": "string", "const": "item" }, "path": { "type": "string" } }, "required": ["from", "path"], "additionalProperties": false }, { "type": "object", "properties": { "from": { "type": "string", "const": "literal" }, "value": {} }, "required": ["from", "value"], "additionalProperties": false }, { "type": "object", "properties": { "from": { "type": "string", "const": "template" }, "parts": { "type": "array", "items": { "type": "string" } }, "expressions": { "type": "array", "items": { "$ref": "#/definitions/InputSource" } } }, "required": ["from", "parts", "expressions"], "additionalProperties": false }], "description": "Input source for step arguments in DSL workflows" }, "WorkflowStepOptions": { "type": "object", "properties": { "description": { "type": "string", "description": "Display name for logs/UI (optional, doesn't affect execution)" }, "retries": { "type": "number", "description": "Number of retry attempts for failed steps (only applies to local execution)" }, "retryDelay": { "type": ["string", "number"], "description": "Delay between retry attempts (e.g., '1s', '2s', '2min')" }, "onError": { "type": "string", "description": "RPC to invoke for compensation when this step fails after exhausting its retries. Mirrors a graph node's `onError`: the handler receives `{ error: { message } }` and the original error is still thrown, so the workflow fails — this is compensation, not recovery." }, "actor": { "$ref": "#/definitions/ScenarioActor", "description": "Run this step as an actor (scenarios). The RPC is sent through the actor's authenticated client over the REAL transport — never dispatched internally — so auth middleware and permissions are exercised end-to-end. The step is recorded durably like any RPC step." } }, "additionalProperties": false, "description": "Workflow step options" }, "ScenarioActor": { "type": "object", "properties": { "name": { "type": "string", "description": "Stable actor name (the key in pikku.config.json's actor registry)." }, "email": { "type": "string", "description": "The actor's user email — flows use it for invites/lookups." } }, "required": ["name", "email"], "additionalProperties": false, "description": "A synthetic user (a user row flagged `actor`) that workflow steps run as over the real transport" }, "ScenarioStepMeta": { "type": "object", "properties": { "type": { "type": "string", "const": "scenarioStep" }, "stepName": { "type": "string", "description": "Cache key (first argument), ordinal-suffixed by the engine when repeated" }, "stepFunc": { "type": "string", "description": "Registered name of the step function being run" }, "phase": { "$ref": "#/definitions/ScenarioStepPhase", "description": "Which keyword the reporter prefixes — given/when/then, or none for `step`" }, "outputVar": { "type": "string", "description": "Output variable name (if assigned)" }, "inputs": { "anyOf": [{ "type": "object", "additionalProperties": { "$ref": "#/definitions/InputSource" } }, { "type": "string", "const": "passthrough" }], "description": "Input source mappings, or 'passthrough' when entire data is passed" }, "options": { "$ref": "#/definitions/WorkflowStepOptions", "description": "Step options" }, "actor": { "type": "string", "description": "Scenario actor name this step runs as ({ actor: actors.x })" }, "browser": { "type": "boolean", "description": "Mirrors the step function's `browser: true` declaration" } }, "required": ["type", "stepName", "stepFunc", "phase"], "additionalProperties": false, "description": "Scenario step metadata — a call to `scenario.step/given/when/then`.\n\nDistinct from RpcStepMeta on purpose: a step runs locally through runPikkuFunc and must never be treated as dispatchable on the queue/replay path, nor registered as a callable RPC (a browser-driving step must not be network-invocable)." }, "ScenarioStepPhase": { "type": "string", "enum": ["step", "given", "when", "then"], "description": "Which Gherkin-style keyword the reporter prefixes this step with. `step` renders no prefix at all." }, "BranchStepMeta": { "type": "object", "properties": { "type": { "type": "string", "const": "branch" }, "branches": { "type": "array", "items": { "$ref": "#/definitions/BranchCase" }, "description": "Branches in order: first is \"if\", rest are \"else if\"" }, "elseSteps": { "type": "array", "items": { "$ref": "#/definitions/WorkflowStepMeta" }, "description": "Else branch steps (when no conditions match)" } }, "required": ["type", "branches"], "additionalProperties": false, "description": "Branch step metadata (if/else-if/else control flow)" }, "BranchCase": { "type": "object", "properties": { "condition": { "$ref": "#/definitions/Condition", "description": "Condition for this branch" }, "steps": { "type": "array", "items": { "$ref": "#/definitions/WorkflowStepMeta" }, "description": "Steps to execute when condition is true" } }, "required": ["condition", "steps"], "additionalProperties": false, "description": "A single branch in an if/else-if chain" }, "Condition": { "anyOf": [{ "$ref": "#/definitions/SimpleCondition" }, { "type": "object", "properties": { "type": { "type": "string", "const": "and" }, "conditions": { "type": "array", "items": { "$ref": "#/definitions/Condition" } } }, "required": ["type", "conditions"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "or" }, "conditions": { "type": "array", "items": { "$ref": "#/definitions/Condition" } } }, "required": ["type", "conditions"], "additionalProperties": false }], "description": "Nested condition structure supporting AND/OR operations" }, "SimpleCondition": { "type": "object", "properties": { "type": { "type": "string", "const": "simple" }, "expression": { "type": "string" } }, "required": ["type", "expression"], "additionalProperties": false, "description": "Simple condition expression (leaf node)" }, "ParallelGroupStepMeta": { "type": "object", "properties": { "type": { "type": "string", "const": "parallel" }, "children": { "type": "array", "items": { "anyOf": [{ "$ref": "#/definitions/RpcStepMeta" }, { "$ref": "#/definitions/ScenarioStepMeta" }] }, "description": "Child steps to execute in parallel" } }, "required": ["type", "children"], "additionalProperties": false, "description": "Parallel group step metadata (Promise.all with multiple steps)" }, "FanoutStepMeta": { "type": "object", "properties": { "type": { "type": "string", "const": "fanout" }, "stepName": { "type": "string", "description": "Step name for this fanout. Optional: a fanout is not itself a cached step, and node ids are step names — borrowing a body step's name would give the loop and that step the same id, collapsing one onto the other." }, "sourceVar": { "type": "string", "description": "Source array variable name" }, "itemVar": { "type": "string", "description": "Iterator variable name" }, "mode": { "type": "string", "enum": ["parallel", "sequential"], "description": "Execution mode" }, "body": { "type": "array", "items": { "anyOf": [{ "$ref": "#/definitions/RpcStepMeta" }, { "$ref": "#/definitions/SleepStepMeta" }, { "$ref": "#/definitions/SuspendStepMeta" }, { "$ref": "#/definitions/ScenarioStepMeta" }] }, "description": "Steps to execute inline per iteration, in order" }, "timeBetween": { "type": "string", "description": "Time between iterations (sequential mode only)" } }, "required": ["type", "sourceVar", "itemVar", "mode", "body"], "additionalProperties": false, "description": "Fanout step metadata (parallel or sequential iteration)" }, "SleepStepMeta": { "type": "object", "properties": { "type": { "type": "string", "const": "sleep", "description": "Sleep step" }, "stepName": { "type": "string", "description": "Cache key (stepName from workflow.sleep)" }, "duration": { "type": ["string", "number"], "description": "Sleep duration" }, "expression": { "type": "string", "description": "Source text of a duration only known at runtime (e.g. a loop variable). The closure evaluates it, so it is legal DSL; it is kept separate from `duration` so regenerated code emits it raw rather than as a string literal, exactly as `expression` does on a set step." } }, "required": ["type", "stepName", "duration"], "additionalProperties": false, "description": "Sleep step metadata" }, "SuspendStepMeta": { "type": "object", "properties": { "type": { "type": "string", "const": "suspend" }, "reason": { "type": "string", "description": "Reason string passed to workflow.suspend() — becomes the durable step key" } }, "required": ["type", "reason"], "additionalProperties": false, "description": "Suspend step metadata (workflow.suspend())" }, "ReturnStepMeta": { "type": "object", "properties": { "type": { "type": "string", "const": "return" }, "outputs": { "type": "object", "additionalProperties": { "$ref": "#/definitions/OutputBinding" }, "description": "Output bindings" }, "spread": { "type": "array", "items": { "type": "string" }, "description": "Variables spread into the returned object (`return { ...r }`), or the sole returned variable (`return r`). Their fields are not enumerable statically, so they are recorded by name rather than expanded into `outputs`." } }, "required": ["type", "outputs"], "additionalProperties": false, "description": "Return step metadata (workflow output)" }, "OutputBinding": { "anyOf": [{ "type": "object", "properties": { "from": { "type": "string", "const": "outputVar" }, "name": { "type": "string" }, "path": { "type": "string" } }, "required": ["from", "name"], "additionalProperties": false }, { "type": "object", "properties": { "from": { "type": "string", "const": "stateVar" }, "name": { "type": "string" }, "path": { "type": "string" } }, "required": ["from", "name"], "additionalProperties": false }, { "type": "object", "properties": { "from": { "type": "string", "const": "input" }, "path": { "type": "string" } }, "required": ["from", "path"], "additionalProperties": false }, { "type": "object", "properties": { "from": { "type": "string", "const": "literal" }, "value": {} }, "required": ["from", "value"], "additionalProperties": false }, { "type": "object", "properties": { "from": { "type": "string", "const": "expression" }, "expression": { "type": "string" } }, "required": ["from", "expression"], "additionalProperties": false }], "description": "Output binding for return statements in DSL workflows" }, "InlineStepMeta": { "type": "object", "properties": { "type": { "type": "string", "const": "inline", "description": "Inline form - local execution" }, "stepName": { "type": "string", "description": "Cache key (stepName from workflow.do)" }, "description": { "type": "string", "description": "Display name" }, "options": { "$ref": "#/definitions/WorkflowStepOptions", "description": "Step options" } }, "required": ["type", "stepName"], "additionalProperties": false, "description": "Inline step metadata (legacy support)" }, "CancelStepMeta": { "type": "object", "properties": { "type": { "type": "string", "const": "cancel", "description": "Cancel step" }, "reason": { "type": "string", "description": "Optional cancellation reason" } }, "required": ["type"], "additionalProperties": false, "description": "Cancel step metadata" }, "ApprovalStepMeta": { "type": "object", "properties": { "type": { "type": "string", "const": "approval" }, "reason": { "type": "string", "description": "Reason string passed to workflow.approval() — becomes the durable step key" }, "outputVar": { "type": "string", "description": "Output variable name (if assigned)" }, "expiry": { "type": ["string", "number"], "description": "Expiry duration, when one was given" } }, "required": ["type", "reason"], "additionalProperties": false, "description": "Approval step metadata (workflow.approval())" }, "SwitchStepMeta": { "type": "object", "properties": { "type": { "type": "string", "const": "switch" }, "expression": { "type": "string", "description": "Expression being switched on" }, "cases": { "type": "array", "items": { "$ref": "#/definitions/SwitchCaseMeta" }, "description": "Case branches" }, "defaultSteps": { "type": "array", "items": { "$ref": "#/definitions/WorkflowStepMeta" }, "description": "Default case steps (optional)" } }, "required": ["type", "expression", "cases"], "additionalProperties": false, "description": "Switch step metadata (switch/case control flow)" }, "SwitchCaseMeta": { "type": "object", "properties": { "value": { "type": ["string", "number", "boolean", "null"], "description": "Case value (literal) or expression" }, "expression": { "type": "string", "description": "Case expression (for complex cases)" }, "steps": { "type": "array", "items": { "$ref": "#/definitions/WorkflowStepMeta" }, "description": "Steps to execute for this case" } }, "required": ["steps"], "additionalProperties": false, "description": "Switch case metadata" }, "FilterStepMeta": { "type": "object", "properties": { "type": { "type": "string", "const": "filter" }, "sourceVar": { "type": "string", "description": "Source array variable name" }, "itemVar": { "type": "string", "description": "Iterator variable name" }, "condition": { "$ref": "#/definitions/Condition", "description": "Filter condition" }, "outputVar": { "type": "string", "description": "Output variable name (if assigned)" } }, "required": ["type", "sourceVar", "itemVar", "condition"], "additionalProperties": false, "description": "Filter step metadata (array.filter)" }, "ArrayPredicateStepMeta": { "type": "object", "properties": { "type": { "type": "string", "const": "arrayPredicate" }, "mode": { "type": "string", "enum": ["some", "every"], "description": "Predicate mode" }, "sourceVar": { "type": "string", "description": "Source array variable name" }, "itemVar": { "type": "string", "description": "Iterator variable name" }, "condition": { "$ref": "#/definitions/Condition", "description": "Predicate condition" }, "outputVar": { "type": "string", "description": "Output variable name (if assigned)" } }, "required": ["type", "mode", "sourceVar", "itemVar", "condition"], "additionalProperties": false, "description": "Array predicate step metadata (array.some, array.every)" }, "SetStepMeta": { "type": "object", "properties": { "type": { "type": "string", "const": "set", "description": "Set step" }, "variable": { "type": "string", "description": "Variable name to set (must be in context)" }, "value": { "description": "Literal value to assign. Mutually exclusive with `expression`." }, "expression": { "type": "string", "description": "Source text of a non-literal assignment (e.g. `count + 1`). Kept separate from `value` so regenerated code can emit it raw — a string `value` is a string literal, an `expression` is code." } }, "required": ["type", "variable"], "additionalProperties": false, "description": "Set step metadata (context variable assignment)" }, "WorkflowContext": { "type": "object", "additionalProperties": { "$ref": "#/definitions/ContextVariable" }, "description": "Workflow context - state variables with defaults and types" }, "ContextVariable": { "type": "object", "properties": { "type": { "type": "string", "enum": ["string", "number", "boolean", "object", "array"], "description": "Variable type" }, "default": { "description": "Default value" }, "description": { "type": "string", "description": "Description for UI/docs" } }, "required": ["type"], "additionalProperties": false, "description": "Context variable definition (serialized from Zod schema or type inference)" }, "FeaturesMeta": { "type": "object", "additionalProperties": { "$ref": "#/definitions/FeatureMeta" } }, "FeatureMeta": { "type": "object", "properties": { "id": { "type": "string", "description": "The export identifier." }, "name": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "entries": { "type": "array", "items": { "$ref": "#/definitions/FeatureMetaEntry" }, "description": "In declared order — a feature's reading order is its declaration order." }, "unresolvedEntries": { "type": "number", "description": "Entries that could not be read statically (a spread, a `.map()`). Their membership is only known once the scenario bootstrap has been evaluated, so a non-zero count means this listing is partial." }, "hasBefore": { "type": "boolean", "description": "Hooks are runtime-only; only their presence is knowable from meta." }, "hasAfter": { "type": "boolean" } }, "required": ["id", "name", "tags", "entries", "unresolvedEntries", "hasBefore", "hasAfter"], "additionalProperties": false, "description": "A feature as the console reads it: the document structure around a group of scenarios. Generated to `scenarios/features.gen.json` and read off disk, so nothing app-facing has to import the scenario bootstrap to describe one." }, "FeatureMetaEntry": { "type": "object", "properties": { "scenario": { "type": "string", "description": "The scenario's declared export name — its key in `WorkflowsMeta`." }, "data": { "description": "The input this entry runs the scenario with — gherkin's `Examples:`." } }, "required": ["scenario"], "additionalProperties": false, "description": "One entry of a feature's scenario list, as extracted from the source." }, "TriggerMeta": { "type": "object", "properties": { "pikkuFuncId": { "type": "string" }, "name": { "type": "string" }, "summary": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "middleware": { "type": "array", "items": { "$ref": "#/definitions/MiddlewareMetadata" } }, "permissions": { "type": "array", "items": { "$ref": "#/definitions/PermissionMetadata" } } }, "required": ["pikkuFuncId", "name"], "additionalProperties": false }, "TriggerSourceMeta": { "type": "object", "properties": { "name": { "type": "string" }, "pikkuFuncId": { "type": "string" }, "packageName": { "type": "string" }, "summary": { "type": "string" }, "description": { "type": "string" } }, "required": ["name", "pikkuFuncId"], "additionalProperties": false }, "MiddlewareGroupsMeta": { "type": "object", "properties": { "definitions": { "type": "object", "additionalProperties": { "$ref": "#/definitions/MiddlewareDefinitionMeta" } }, "instances": { "type": "object", "additionalProperties": { "$ref": "#/definitions/MiddlewareInstanceMeta" } }, "httpGroups": { "type": "object", "additionalProperties": { "$ref": "#/definitions/GroupMeta" } }, "tagGroups": { "type": "object", "additionalProperties": { "$ref": "#/definitions/GroupMeta" } } }, "required": ["definitions", "instances", "httpGroups", "tagGroups"], "additionalProperties": false }, "MiddlewareDefinitionMeta": { "type": "object", "properties": { "services": { "type": "object", "properties": { "optimized": { "type": "boolean" }, "services": { "type": "array", "items": { "type": "string" } } }, "required": ["optimized", "services"], "additionalProperties": false }, "sourceFile": { "type": "string" }, "position": { "type": "number" }, "exportedName": { "type": ["string", "null"] }, "factory": { "type": "boolean" }, "name": { "type": "string" }, "description": { "type": "string" }, "package": { "type": "string" } }, "required": ["services", "sourceFile", "position", "exportedName"], "additionalProperties": false }, "MiddlewareInstanceMeta": { "type": "object", "properties": { "definitionId": { "type": "string" }, "sourceFile": { "type": "string" }, "position": { "type": "number" }, "isFactoryCall": { "type": "boolean" } }, "required": ["definitionId", "sourceFile", "position", "isFactoryCall"], "additionalProperties": false }, "GroupMeta": { "type": "object", "properties": { "exportName": { "type": ["string", "null"] }, "sourceFile": { "type": "string" }, "position": { "type": "number" }, "services": { "type": "object", "properties": { "optimized": { "type": "boolean" }, "services": { "type": "array", "items": { "type": "string" } } }, "required": ["optimized", "services"], "additionalProperties": false }, "count": { "type": "number" }, "instanceIds": { "type": "array", "items": { "type": "string" } }, "isFactory": { "type": "boolean" } }, "required": ["exportName", "sourceFile", "position", "services", "count", "instanceIds", "isFactory"], "additionalProperties": false }, "PermissionsGroupsMeta": { "type": "object", "properties": { "definitions": { "type": "object", "additionalProperties": { "$ref": "#/definitions/PermissionDefinitionMeta" } } }, "required": ["definitions"], "additionalProperties": false }, "PermissionDefinitionMeta": { "type": "object", "properties": { "services": { "type": "object", "properties": { "optimized": { "type": "boolean" }, "services": { "type": "array", "items": { "type": "string" } } }, "required": ["optimized", "services"], "additionalProperties": false }, "sourceFile": { "type": "string" }, "position": { "type": "number" }, "exportedName": { "type": ["string", "null"] }, "factory": { "type": "boolean" }, "name": { "type": "string" }, "description": { "type": "string" } }, "required": ["services", "sourceFile", "position", "exportedName"], "additionalProperties": false }, "AgentsMeta": { "$ref": "#/definitions/AIAgentMeta" }, "AIAgentMeta": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": false, "properties": { "tools": { "type": "array", "items": { "type": "string" } }, "agents": { "type": "array", "items": { "type": "string" } }, "workflows": { "type": "array", "items": { "type": "string" } }, "inputSchema": { "type": ["string", "null"] }, "outputSchema": { "type": ["string", "null"] }, "workingMemorySchema": { "type": ["string", "null"] }, "middleware": { "type": "array", "items": { "$ref": "#/definitions/MiddlewareMetadata" } }, "channelMiddleware": { "type": "array", "items": { "$ref": "#/definitions/MiddlewareMetadata" } }, "aiMiddleware": { "type": "array", "items": { "$ref": "#/definitions/MiddlewareMetadata" } }, "permissions": { "type": "array", "items": { "$ref": "#/definitions/PermissionMetadata" } }, "sourceFile": { "type": "string" }, "exportedName": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "summary": { "type": "string" }, "errors": { "type": "array", "items": { "type": "string" } }, "role": { "type": "string" }, "personality": { "type": "string" }, "goal": { "type": "string" }, "model": { "type": "string" }, "temperature": { "type": "number" }, "sessionScope": { "$ref": "#/definitions/SessionScope", "description": "Ownership/partitioning of this agent's threads and runs. Defaults to `'user'`." }, "agentMode": { "type": "string", "enum": ["delegate", "supervise"] }, "memory": { "$ref": "#/definitions/AIAgentMemoryConfig" }, "maxSteps": { "type": "number" }, "toolChoice": { "type": "string", "enum": ["auto", "required", "none"] }, "tags": { "type": "array", "items": { "type": "string" } }, "prepareStep": { "$comment": "(ctx: {\n stepNumber: number;\n messages: AIMessage[];\n tools: AIAgentToolDef[];\n toolChoice: 'auto' \| 'required' \| 'none';\n model: string;\n stop: () => void;\n }) => void \| Promise<void>", "type": "object", "properties": { "namedArgs": { "type": "object", "properties": { "ctx": { "type": "object", "properties": { "stepNumber": { "type": "number" }, "messages": { "type": "array", "items": { "$ref": "#/definitions/AIMessage" } }, "tools": { "type": "array", "items": { "$ref": "#/definitions/AIAgentToolDef" } }, "toolChoice": { "type": "string", "enum": ["auto", "required", "none"] }, "model": { "type": "string" }, "stop": { "$comment": "() => void" } }, "required": ["stepNumber", "messages", "tools", "toolChoice", "model", "stop"], "additionalProperties": false } }, "required": ["ctx"], "additionalProperties": false } } }, "auth": { "type": "boolean", "description": "Whether a session is required to run this agent. Defaults to `false`, since agents are commonly invoked from an already-authenticated `pikkuFunc` or from genuinely sessionless contexts (crons, queue workers). Set `true` to require a session at the agent itself. `scopes` and `permissions` are enforced either way." }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "Scopes the session must hold to run this agent. All of them are required (AND), and they are checked before `permissions` — unlike permissions, which OR together, a scope can only narrow access.\n\nNarrowed to the generated `ScopeId` union in a project's own `pikku-types.gen.ts`, so an undeclared scope is a compile error." } }, "required": ["description", "goal", "inputSchema", "model", "name", "outputSchema", "workingMemorySchema"] } }, "SessionScope": { "type": "string", "enum": ["user", "org"], "description": "How an agent's threads/runs are owned and partitioned.\n- `'user'` (default): owner is the authenticated `session.userId`; the caller's `resourceId` becomes a sub-partition within that user (`userId:resourceId`).\n- `'org'`: owner is the authenticated `session.orgId` (`orgId:resourceId`), so threads are shared across everyone in the org. Requires a session with an org (e.g. Better Auth's `organization` plugin) — otherwise access is denied.\n\nThe trusted principal is always the prefix, so a client-supplied `resourceId` can sub-divide within the caller's own boundary but can never widen access to another user's or org's threads." }, "AIAgentMemoryConfig": { "type": "object", "properties": { "storage": { "type": "string" }, "vector": { "type": "string" }, "embedder": { "type": "string" }, "lastMessages": { "type": "number" }, "workingMemory": {} }, "additionalProperties": false }, "AIMessage": { "type": "object", "properties": { "id": { "type": "string" }, "role": { "type": "string", "enum": ["system", "user", "assistant", "tool"] }, "content": { "anyOf": [{ "type": "string" }, { "type": "array", "items": { "$ref": "#/definitions/AIContentPart" } }] }, "toolCalls": { "type": "array", "items": { "$ref": "#/definitions/AIToolCall" } }, "toolResults": { "type": "array", "items": { "$ref": "#/definitions/AIToolResult" } }, "reasoningContent": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": ["id", "role", "createdAt"], "additionalProperties": false }, "AIContentPart": { "anyOf": [{ "type": "object", "properties": { "type": { "type": "string", "const": "text" }, "text": { "type": "string" } }, "required": ["type", "text"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "image" }, "data": { "type": "string" }, "url": { "type": "string" }, "mediaType": { "type": "string" } }, "required": ["type"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "file" }, "data": { "type": "string" }, "url": { "type": "string" }, "mediaType": { "type": "string" }, "filename": { "type": "string" } }, "required": ["type", "mediaType"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "data" }, "name": { "type": "string" }, "data": {} }, "required": ["type", "name", "data"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "generative-ui" }, "spec": {} }, "required": ["type", "spec"], "additionalProperties": false }] }, "AIToolCall": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "args": { "type": "object", "additionalProperties": {} } }, "required": ["id", "name", "args"], "additionalProperties": false }, "AIToolResult": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "result": { "type": "string" } }, "required": ["id", "name", "result"], "additionalProperties": false }, "AIAgentToolDef": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "inputSchema": { "type": "object", "additionalProperties": {} }, "execute": { "$comment": "(input: unknown) => Promise<unknown>", "type": "object", "properties": { "namedArgs": { "type": "object", "properties": { "input": {} }, "required": ["input"], "additionalProperties": false } } }, "needsApproval": { "type": "boolean" }, "approvalDescriptionFn": { "$comment": "(input: unknown) => Promise<string>", "type": "object", "properties": { "namedArgs": { "type": "object", "properties": { "input": {} }, "required": ["input"], "additionalProperties": false } } }, "forwardsApproval": { "type": "boolean", "description": "Set only by the framework on sub-agent delegating tools. Such a tool may legitimately return an `__approvalRequired` marker to forward a nested sub-agent approval. The marker is honored ONLY from a tool with this flag — a plain tool's output (which an attacker may influence) can never forge an approval request. See `checkForApprovals`." } }, "required": ["name", "description", "inputSchema", "execute"], "additionalProperties": false }, "EmailsMeta": { "type": "object", "properties": { "src": { "type": "string" }, "themeHash": { "type": "string" }, "templates": { "type": "object", "additionalProperties": { "$ref": "#/definitions/EmailTemplateMeta" } } }, "required": ["src", "themeHash", "templates"], "additionalProperties": false }, "EmailTemplateMeta": { "type": "object", "properties": { "variables": { "type": "array", "items": { "type": "string" } }, "hasHtml": { "type": "boolean" }, "hasSubject": { "type": "boolean" }, "hasText": { "type": "boolean" }, "locales": { "type": "object", "additionalProperties": { "$ref": "#/definitions/EmailTemplateLocaleMeta" } } }, "required": ["variables", "hasHtml", "hasSubject", "hasText", "locales"], "additionalProperties": false }, "EmailTemplateLocaleMeta": { "type": "object", "properties": { "contentHash": { "type": "string" }, "htmlHash": { "type": "string" }, "subjectHash": { "type": "string" }, "textHash": { "type": "string" } }, "required": ["contentHash", "htmlHash", "subjectHash", "textHash"], "additionalProperties": false }, "FunctionUsedBy": { "type": "object", "properties": { "transports": { "type": "array", "items": { "$ref": "#/definitions/WiringRef" } }, "jobs": { "type": "array", "items": { "$ref": "#/definitions/WiringRef" } }, "workflows": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": ["id", "name"], "additionalProperties": false } } }, "required": ["transports", "jobs", "workflows"], "additionalProperties": false }, "WiringRef": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" } }, "required": ["type", "id", "name"], "additionalProperties": false }, "MetaCounts": { "type": "object", "properties": { "functions": { "type": "number" }, "workflows": { "type": "number" }, "httpRoutes": { "type": "number" }, "channels": { "type": "number" }, "mcpTools": { "type": "number" }, "gateways": { "type": "number" }, "schedulers": { "type": "number" }, "queues": { "type": "number" }, "cliCommands": { "type": "number" }, "rpcMethods": { "type": "number" }, "triggers": { "type": "number" }, "triggerSources": { "type": "number" }, "agents": { "type": "number" }, "emails": { "type": "number" }, "secrets": { "type": "number" }, "variables": { "type": "number" } }, "required": ["functions", "workflows", "httpRoutes", "channels", "mcpTools", "gateways", "schedulers", "queues", "cliCommands", "rpcMethods", "triggers", "triggerSources", "agents", "emails", "secrets", "variables"], "additionalProperties": false } } }
1	+ { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "functions": { "type": "array", "items": { "$ref": "#/definitions/FunctionMeta" } }, "httpMeta": { "type": "array", "items": { "$ref": "#/definitions/HttpRouteMeta" } }, "cliMeta": { "type": "array", "items": { "$ref": "#/definitions/CliProgramMeta" } }, "cliRenderers": { "type": "object", "additionalProperties": { "$ref": "#/definitions/CliRendererMeta" } }, "channelsMeta": { "type": "object", "additionalProperties": { "$ref": "#/definitions/ChannelMeta" } }, "queueMeta": { "type": "object", "additionalProperties": { "$ref": "#/definitions/QueueWorkerMeta" } }, "schedulerMeta": { "type": "object", "additionalProperties": { "$ref": "#/definitions/SchedulerTaskMeta" } }, "rpcMeta": { "type": "object", "additionalProperties": { "$ref": "#/definitions/RpcMeta" } }, "mcpMeta": { "type": "array", "items": { "$ref": "#/definitions/McpItemMeta" } }, "gatewayMeta": { "type": "array", "items": { "$ref": "#/definitions/GatewayItemMeta" } }, "workflows": { "$ref": "#/definitions/WorkflowsMeta" }, "personas": { "type": "object", "additionalProperties": { "$ref": "#/definitions/ResolvedPersona" } }, "systemRoles": { "$ref": "#/definitions/SystemRoleDefinitionsMeta", "description": "The roles declared with `defineSystemRole`, keyed by name.\n\nShipped alongside the personas because a persona only ever names roles, and nothing about what they can reach is readable without the scopes each one confers." }, "features": { "$ref": "#/definitions/FeaturesMeta" }, "triggerMeta": { "type": "object", "additionalProperties": { "$ref": "#/definitions/TriggerMeta" } }, "triggerSourceMeta": { "type": "object", "additionalProperties": { "$ref": "#/definitions/TriggerSourceMeta" } }, "middlewareGroupsMeta": { "$ref": "#/definitions/MiddlewareGroupsMeta" }, "permissionsGroupsMeta": { "$ref": "#/definitions/PermissionsGroupsMeta" }, "agentsMeta": { "$ref": "#/definitions/AgentsMeta" }, "emailsMeta": { "$ref": "#/definitions/EmailsMeta" }, "secretsMeta": { "type": "object", "additionalProperties": {} }, "credentialsMeta": { "type": "object", "additionalProperties": {} }, "variablesMeta": { "type": "object", "additionalProperties": {} }, "functionUsedBy": { "type": "object", "additionalProperties": { "$ref": "#/definitions/FunctionUsedBy" } }, "counts": { "$ref": "#/definitions/MetaCounts" } }, "required": ["agentsMeta", "channelsMeta", "cliMeta", "cliRenderers", "counts", "credentialsMeta", "emailsMeta", "features", "functionUsedBy", "functions", "gatewayMeta", "httpMeta", "mcpMeta", "middlewareGroupsMeta", "permissionsGroupsMeta", "personas", "queueMeta", "rpcMeta", "schedulerMeta", "secretsMeta", "systemRoles", "triggerMeta", "triggerSourceMeta", "variablesMeta", "workflows"], "additionalProperties": false, "definitions": { "FunctionMeta": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string" }, "functionType": { "type": "string", "enum": ["user", "inline", "helper", "remote"], "description": "`remote`: a contract with no local body, answered by a connected client." }, "funcWrapper": { "type": "string" }, "services": { "$ref": "#/definitions/FunctionServicesMeta" }, "wires": { "$ref": "#/definitions/FunctionWiresMeta" }, "inputs": { "anyOf": [{ "type": "array", "items": { "type": "string" } }, { "type": "null" }] }, "outputs": { "anyOf": [{ "type": "array", "items": { "type": "string" } }, { "type": "null" }] }, "middleware": { "type": "array", "items": { "$ref": "#/definitions/MiddlewareMetadata" } }, "permissions": { "type": "array", "items": { "$ref": "#/definitions/PermissionMetadata" } }, "isDirectFunction": { "type": "boolean" }, "sourceFile": { "type": "string" }, "exportedName": { "type": "string" }, "bodySourceFile": { "type": "string", "description": "File containing the handler body when it differs from sourceFile (imported handlers)" }, "bodyStart": { "type": "number", "description": "1-indexed first line of the handler body (verbose meta; coverage mapping)" }, "bodyEnd": { "type": "number", "description": "1-indexed last line of the handler body (verbose meta; coverage mapping)" }, "pikkuFuncId": { "type": "string" }, "packageName": { "type": "string" }, "title": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "summary": { "type": "string" }, "description": { "type": "string" }, "errors": { "type": "array", "items": { "type": "string" } }, "inputSchemaName": { "type": ["string", "null"] }, "outputSchemaName": { "type": ["string", "null"] }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "Scopes the session must hold to run this function. All are required (AND)." }, "expose": { "type": "boolean" }, "auth": { "type": "boolean", "description": "A sessionless function's own `auth: true`. `sessionless` carries the baseline — a `pikkuFunc` always requires a session — and this carries the tightening a `pikkuSessionlessFunc` applies to itself. Both are needed to know whether a function is gated without running it." }, "selfAuthenticated": { "type": "boolean", "description": "The author's declaration that this function authorizes callers in its own body. Carries no runtime effect — it records a gate codegen cannot see, so an audit is not left to guess whether a sessionless function is open." }, "remote": { "type": "boolean" }, "scenarioStep": { "type": "boolean", "description": "A step RPC: invoked by name only from a scenario run and refused everywhere else, so it is never network-callable." }, "scenario": { "type": "boolean", "description": "The body of a `pikkuScenario(...)`. Only ever run by `pikku scenario run`, so it is held back from the app bootstrap and from every deployed unit." }, "mcp": { "type": "boolean" }, "readonly": { "type": "boolean" }, "deploy": { "type": "string", "enum": ["serverless", "server", "auto"] }, "sessionless": { "type": "boolean" }, "workflowQueued": { "type": "boolean", "description": "When true, workflow steps calling this function are dispatched via the queue. No queue service configured is a hard error." }, "workflowRetries": { "type": "number", "description": "Retry count when this function is used as a workflow step." }, "workflowTimeout": { "type": "string", "description": "Timeout when this function is used as a workflow step (e.g. '30s', '5m')." }, "scenarioStepSurfaces": { "type": "array", "items": { "$ref": "#/definitions/ScenarioSurface" }, "description": "Scenario steps only: which surfaces this step declares a binding for.\n\nThe reporter derives coverage from this — a `then` with no binding for the surface the run targeted was never actually witnessed there, which is a gap worth counting rather than excusing." }, "scenarioStepKind": { "$ref": "#/definitions/ScenarioStepKind", "description": "Scenario steps only: who acts. Absent means `persona` — the ordinary step, and the only kind that existed before the other two.\n\nA `platform` or `addon` step is the app or a third-party system acting, and it must never reach a virtual user's catalogue. That is not tidiness: a virtual user that can invoke \"Stripe's webhook arrives\" can forge its own payment success, and every finding downstream of that is worthless." }, "scenarioStepAddon": { "type": "string", "description": "Addon steps only: the addon whose system acts — `wireAddon`'s `name`." }, "scenarioStepTemplate": { "type": "string", "description": "Scenario steps only: the prose a reporter renders, with `{placeholders}` filled from the step's recorded input." }, "secretBroker": { "type": "boolean", "description": "Keeps the full `SecretService`. Set by the inspector, read by the runner." }, "version": { "type": "number" }, "approvalRequired": { "type": "boolean" }, "approvalDescription": { "type": "string" }, "implementationHash": { "type": "string" }, "contractHash": { "type": "string" }, "inputHash": { "type": "string" }, "outputHash": { "type": "string" } }, "required": ["inputSchemaName", "outputSchemaName", "pikkuFuncId"] }, "FunctionServicesMeta": { "type": "object", "properties": { "optimized": { "type": "boolean" }, "services": { "type": "array", "items": { "type": "string" } } }, "required": ["optimized", "services"], "additionalProperties": false }, "FunctionWiresMeta": { "type": "object", "properties": { "optimized": { "type": "boolean" }, "wires": { "type": "array", "items": { "type": "string" } } }, "required": ["optimized", "wires"], "additionalProperties": false }, "MiddlewareMetadata": { "anyOf": [{ "type": "object", "properties": { "type": { "type": "string", "const": "http" }, "route": { "type": "string" } }, "required": ["type", "route"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "tag" }, "tag": { "type": "string" } }, "required": ["type", "tag"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "wire" }, "name": { "type": "string" }, "inline": { "type": "boolean" } }, "required": ["type", "name"], "additionalProperties": false }] }, "PermissionMetadata": { "type": "object", "properties": { "type": { "type": "string", "const": "wire" }, "name": { "type": "string" }, "inline": { "type": "boolean" } }, "required": ["type", "name"], "additionalProperties": false, "description": "A reference to a permission function, resolved by name. Function-scoped only: there are no wire- or tag-level permission references." }, "ScenarioSurface": { "type": "string", "enum": ["browser", "cli", "default"], "description": "How an actor drives the system for one step.\n\nA step declares one implementation per surface it supports, and the runner picks between them — so the same ladder can run through a real browser, over the websocket, or entirely server-side.\n\n`default` is the floor: it is what every other surface falls back to, so it can never itself fall back." }, "ScenarioStepKind": { "type": "string", "enum": ["persona", "platform", "addon"], "description": "Who acts in a step.\n\n`persona` is a person driving the system through one of its surfaces — the ordinary `pikkuScenarioStep`. `platform` is the app acting on itself (\"the platform has expired the trial\"), and `addon` is a third-party system acting on it (\"Stripe's webhook arrives\"), contributed by the addon that wraps that service.\n\nThe three are separate declarations rather than a field on one, so the inspector verifies a step's kind by which function was called rather than by trusting a string literal — and so an addon package exports only addon steps, which is checkable." }, "HttpRouteMeta": { "type": "object", "properties": { "pikkuFuncId": { "type": "string" }, "route": { "type": "string" }, "method": { "type": "string" }, "params": { "type": "array", "items": { "type": "string" } }, "query": { "type": "array", "items": { "type": "string" } }, "summary": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "errors": { "type": "array", "items": { "type": "string" } }, "auth": { "type": "boolean" }, "sse": { "type": "boolean" }, "middleware": { "type": "array", "items": { "$ref": "#/definitions/MiddlewareMetadata" } }, "permissions": { "type": "array", "items": { "$ref": "#/definitions/PermissionMetadata" } }, "inputSchemaName": { "type": "string" }, "outputSchemaName": { "type": "string" } }, "required": ["pikkuFuncId", "route", "method"], "additionalProperties": false }, "CliProgramMeta": { "type": "object", "properties": { "wireId": { "type": "string" }, "program": { "type": "string" }, "description": { "type": "string" }, "commands": { "type": "object", "additionalProperties": { "$ref": "#/definitions/CliCommandMeta" } }, "options": { "type": "object", "additionalProperties": { "$ref": "#/definitions/CliOptionMeta" } }, "defaultRenderName": { "type": "string" } }, "required": ["wireId", "program", "commands", "options"], "additionalProperties": false }, "CliCommandMeta": { "type": "object", "properties": { "pikkuFuncId": { "type": "string" }, "description": { "type": "string" }, "summary": { "type": "string" }, "parameters": { "type": "string" }, "positionals": { "type": "array", "items": { "$ref": "#/definitions/CliPositionalMeta" } }, "options": { "type": "object", "additionalProperties": { "$ref": "#/definitions/CliOptionMeta" } }, "renderName": { "type": "string" }, "subcommands": { "type": "object", "additionalProperties": { "$ref": "#/definitions/CliCommandMeta" } }, "isDefault": { "type": "boolean" } }, "required": ["pikkuFuncId", "positionals", "options"], "additionalProperties": false }, "CliPositionalMeta": { "type": "object", "properties": { "name": { "type": "string" }, "required": { "type": "boolean" }, "variadic": { "type": "boolean" } }, "required": ["name", "required"], "additionalProperties": false }, "CliOptionMeta": { "type": "object", "properties": { "description": { "type": "string" }, "short": { "type": "string" }, "default": {}, "choices": { "type": "array", "items": {} }, "array": { "type": "boolean" }, "required": { "type": "boolean" } }, "required": ["description"], "additionalProperties": false }, "CliRendererMeta": { "type": "object", "properties": { "name": { "type": "string" }, "exportedName": { "type": "string" }, "filePath": { "type": "string" }, "services": { "type": "object", "properties": { "optimized": { "type": "boolean" }, "services": { "type": "array", "items": { "type": "string" } } }, "required": ["optimized", "services"], "additionalProperties": false } }, "required": ["name", "filePath", "services"], "additionalProperties": false }, "ChannelMeta": { "type": "object", "properties": { "name": { "type": "string" }, "route": { "type": "string" }, "params": { "type": "array", "items": { "type": "string" } }, "query": { "type": "array", "items": { "type": "string" } }, "input": { "type": ["string", "null"] }, "connect": { "anyOf": [{ "$ref": "#/definitions/ChannelMessageMeta" }, { "type": "null" }] }, "disconnect": { "anyOf": [{ "$ref": "#/definitions/ChannelMessageMeta" }, { "type": "null" }] }, "message": { "anyOf": [{ "$ref": "#/definitions/ChannelMessageMeta" }, { "type": "null" }] }, "messageWirings": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "$ref": "#/definitions/ChannelMessageMeta" } } }, "summary": { "type": "string" }, "description": { "type": "string" }, "errors": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "middleware": { "type": "array", "items": { "$ref": "#/definitions/MiddlewareMetadata" } }, "permissions": { "type": "array", "items": { "$ref": "#/definitions/PermissionMetadata" } } }, "required": ["name", "route", "input", "connect", "disconnect", "message", "messageWirings"], "additionalProperties": false }, "ChannelMessageMeta": { "type": "object", "properties": { "pikkuFuncId": { "type": "string" }, "summary": { "type": "string" }, "description": { "type": "string" }, "errors": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "middleware": { "type": "array", "items": { "$ref": "#/definitions/MiddlewareMetadata" } }, "permissions": { "type": "array", "items": { "$ref": "#/definitions/PermissionMetadata" } } }, "required": ["pikkuFuncId"], "additionalProperties": false }, "QueueWorkerMeta": { "type": "object", "properties": { "pikkuFuncId": { "type": "string" }, "queueName": { "type": "string" }, "summary": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "middleware": { "type": "array", "items": { "$ref": "#/definitions/MiddlewareMetadata" } }, "permissions": { "type": "array", "items": { "$ref": "#/definitions/PermissionMetadata" } }, "config": { "type": "object", "additionalProperties": {} } }, "required": ["pikkuFuncId", "queueName"], "additionalProperties": false }, "SchedulerTaskMeta": { "type": "object", "properties": { "pikkuFuncId": { "type": "string" }, "name": { "type": "string" }, "schedule": { "type": "string" }, "summary": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "middleware": { "type": "array", "items": { "$ref": "#/definitions/MiddlewareMetadata" } }, "permissions": { "type": "array", "items": { "$ref": "#/definitions/PermissionMetadata" } } }, "required": ["pikkuFuncId", "name", "schedule"], "additionalProperties": false }, "RpcMeta": { "type": "object", "properties": { "pikkuFuncId": { "type": "string" } }, "required": ["pikkuFuncId"], "additionalProperties": false }, "McpItemMeta": { "type": "object", "properties": { "pikkuFuncId": { "type": "string" }, "method": { "type": "string", "enum": ["resource", "tool", "prompt"] }, "name": { "type": "string" }, "wireId": { "type": "string" }, "description": { "type": "string" }, "summary": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "errors": { "type": "array", "items": { "type": "string" } }, "uri": { "type": "string" }, "arguments": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "required": { "type": "boolean" } }, "required": ["name"], "additionalProperties": false } }, "middleware": { "type": "array", "items": { "$ref": "#/definitions/MiddlewareMetadata" } }, "permissions": { "type": "array", "items": { "$ref": "#/definitions/PermissionMetadata" } }, "inputSchemaName": { "type": "string" }, "outputSchemaName": { "type": "string" } }, "required": ["pikkuFuncId", "method"], "additionalProperties": false }, "GatewayItemMeta": { "type": "object", "properties": { "pikkuFuncId": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string", "enum": ["webhook", "websocket", "listener"] }, "route": { "type": "string" }, "platform": { "type": "string" }, "packageName": { "type": "string" }, "summary": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "errors": { "type": "array", "items": { "type": "string" } }, "auth": { "type": "boolean" }, "gateway": { "type": "boolean", "const": true }, "middleware": { "type": "array", "items": { "$ref": "#/definitions/MiddlewareMetadata" } }, "permissions": { "type": "array", "items": { "$ref": "#/definitions/PermissionMetadata" } } }, "required": ["pikkuFuncId", "name", "type", "gateway"], "additionalProperties": false }, "WorkflowsMeta": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string" }, "steps": { "type": "array", "items": { "$ref": "#/definitions/WorkflowStepMeta" } }, "context": { "$ref": "#/definitions/WorkflowContext" }, "dsl": { "type": "boolean" }, "expose": { "type": "boolean" }, "scenario": { "type": "boolean" }, "skip": { "type": "string" }, "actors": { "type": "array", "items": { "type": "string" } }, "pikkuFuncId": { "type": "string" }, "packageName": { "type": "string" }, "title": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "summary": { "type": "string" }, "description": { "type": "string" }, "errors": { "type": "array", "items": { "type": "string" } }, "middleware": { "type": "array", "items": { "$ref": "#/definitions/MiddlewareMetadata" } }, "permissions": { "type": "array", "items": { "$ref": "#/definitions/PermissionMetadata" } } }, "required": ["name", "pikkuFuncId", "steps"] } }, "WorkflowStepMeta": { "anyOf": [{ "$ref": "#/definitions/RpcStepMeta" }, { "$ref": "#/definitions/ScenarioStepMeta" }, { "$ref": "#/definitions/BranchStepMeta" }, { "$ref": "#/definitions/ParallelGroupStepMeta" }, { "$ref": "#/definitions/FanoutStepMeta" }, { "$ref": "#/definitions/ReturnStepMeta" }, { "$ref": "#/definitions/InlineStepMeta" }, { "$ref": "#/definitions/SleepStepMeta" }, { "$ref": "#/definitions/CancelStepMeta" }, { "$ref": "#/definitions/SuspendStepMeta" }, { "$ref": "#/definitions/ApprovalStepMeta" }, { "$ref": "#/definitions/SwitchStepMeta" }, { "$ref": "#/definitions/FilterStepMeta" }, { "$ref": "#/definitions/ArrayPredicateStepMeta" }, { "$ref": "#/definitions/SetStepMeta" }], "description": "Workflow step metadata (extracted by inspector)" }, "RpcStepMeta": { "type": "object", "properties": { "type": { "type": "string", "const": "rpc", "description": "RPC form - generates queue worker" }, "stepName": { "type": "string", "description": "Cache key (stepName from workflow.do)" }, "rpcName": { "type": "string", "description": "RPC to invoke" }, "outputVar": { "type": "string", "description": "Output variable name (if assigned)" }, "inputs": { "anyOf": [{ "type": "object", "additionalProperties": { "$ref": "#/definitions/InputSource" } }, { "type": "string", "const": "passthrough" }], "description": "Input source mappings, or 'passthrough' when entire data is passed" }, "options": { "$ref": "#/definitions/WorkflowStepOptions", "description": "Step options" }, "actor": { "type": "string", "description": "Scenario actor name this step runs as ({ actor: actors.x })" }, "expectEventually": { "type": "boolean", "description": "True for workflow.expectEventually polling steps" } }, "required": ["type", "stepName", "rpcName"], "additionalProperties": false, "description": "RPC step metadata (base form)" }, "InputSource": { "anyOf": [{ "type": "object", "properties": { "from": { "type": "string", "const": "input" }, "path": { "type": "string" } }, "required": ["from", "path"], "additionalProperties": false }, { "type": "object", "properties": { "from": { "type": "string", "const": "outputVar" }, "name": { "type": "string" }, "path": { "type": "string" } }, "required": ["from", "name"], "additionalProperties": false }, { "type": "object", "properties": { "from": { "type": "string", "const": "item" }, "path": { "type": "string" } }, "required": ["from", "path"], "additionalProperties": false }, { "type": "object", "properties": { "from": { "type": "string", "const": "literal" }, "value": {} }, "required": ["from", "value"], "additionalProperties": false }, { "type": "object", "properties": { "from": { "type": "string", "const": "template" }, "parts": { "type": "array", "items": { "type": "string" } }, "expressions": { "type": "array", "items": { "$ref": "#/definitions/InputSource" } } }, "required": ["from", "parts", "expressions"], "additionalProperties": false }], "description": "Input source for step arguments in DSL workflows" }, "WorkflowStepOptions": { "type": "object", "properties": { "description": { "type": "string", "description": "Display name for logs/UI (optional, doesn't affect execution)" }, "retries": { "type": "number", "description": "Number of retry attempts for failed steps (only applies to local execution)" }, "retryDelay": { "type": ["string", "number"], "description": "Delay between retry attempts (e.g., '1s', '2s', '2min')" }, "onError": { "type": "string", "description": "RPC to invoke for compensation when this step fails after exhausting its retries. Mirrors a graph node's `onError`: the handler receives `{ error: { message } }` and the original error is still thrown, so the workflow fails — this is compensation, not recovery." }, "actor": { "$ref": "#/definitions/ScenarioPersona", "description": "Run this step as an actor (scenarios). The RPC is sent through the actor's authenticated client over the REAL transport — never dispatched internally — so auth middleware and permissions are exercised end-to-end. The step is recorded durably like any RPC step." } }, "additionalProperties": false, "description": "Workflow step options" }, "ScenarioPersona": { "type": "object", "properties": { "name": { "type": "string", "description": "The id it was declared under — what a step's `actor` slot names." }, "email": { "type": "string", "description": "Their address, computed from the id. Flows use it for invites/lookups." } }, "required": ["name", "email"], "additionalProperties": false, "description": "A declared person, signed in and acting over the real transport.\n\nThe runtime half of `definePersonas()`: sign-in materialises a user row flagged `actor: true`, and everything a step or a virtual user does goes through here." }, "ScenarioStepMeta": { "type": "object", "properties": { "type": { "type": "string", "const": "scenarioStep" }, "stepName": { "type": "string", "description": "Cache key (first argument), ordinal-suffixed by the engine when repeated" }, "stepFunc": { "type": "string", "description": "Registered name of the step function being run" }, "phase": { "$ref": "#/definitions/ScenarioStepPhase", "description": "Which keyword the reporter prefixes — given/when/then, or none for `step`" }, "outputVar": { "type": "string", "description": "Output variable name (if assigned)" }, "inputs": { "anyOf": [{ "type": "object", "additionalProperties": { "$ref": "#/definitions/InputSource" } }, { "type": "string", "const": "passthrough" }], "description": "Input source mappings, or 'passthrough' when entire data is passed" }, "options": { "$ref": "#/definitions/WorkflowStepOptions", "description": "Step options" }, "actor": { "type": "string", "description": "Scenario actor name this step runs as ({ actor: actors.x })" }, "surfaces": { "type": "array", "items": { "$ref": "#/definitions/ScenarioSurface" }, "description": "Mirrors the surfaces the step function declares a binding for" } }, "required": ["type", "stepName", "stepFunc", "phase"], "additionalProperties": false, "description": "Scenario step metadata — a call to `scenario.step/given/when/then`.\n\nDistinct from RpcStepMeta on purpose: a step runs locally through runPikkuFunc and must never be treated as dispatchable on the queue/replay path, nor registered as a callable RPC (a browser-driving step must not be network-invocable)." }, "ScenarioStepPhase": { "type": "string", "enum": ["step", "given", "when", "then"], "description": "Which Gherkin-style keyword the reporter prefixes this step with. `step` renders no prefix at all." }, "BranchStepMeta": { "type": "object", "properties": { "type": { "type": "string", "const": "branch" }, "branches": { "type": "array", "items": { "$ref": "#/definitions/BranchCase" }, "description": "Branches in order: first is \"if\", rest are \"else if\"" }, "elseSteps": { "type": "array", "items": { "$ref": "#/definitions/WorkflowStepMeta" }, "description": "Else branch steps (when no conditions match)" } }, "required": ["type", "branches"], "additionalProperties": false, "description": "Branch step metadata (if/else-if/else control flow)" }, "BranchCase": { "type": "object", "properties": { "condition": { "$ref": "#/definitions/Condition", "description": "Condition for this branch" }, "steps": { "type": "array", "items": { "$ref": "#/definitions/WorkflowStepMeta" }, "description": "Steps to execute when condition is true" } }, "required": ["condition", "steps"], "additionalProperties": false, "description": "A single branch in an if/else-if chain" }, "Condition": { "anyOf": [{ "$ref": "#/definitions/SimpleCondition" }, { "type": "object", "properties": { "type": { "type": "string", "const": "and" }, "conditions": { "type": "array", "items": { "$ref": "#/definitions/Condition" } } }, "required": ["type", "conditions"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "or" }, "conditions": { "type": "array", "items": { "$ref": "#/definitions/Condition" } } }, "required": ["type", "conditions"], "additionalProperties": false }], "description": "Nested condition structure supporting AND/OR operations" }, "SimpleCondition": { "type": "object", "properties": { "type": { "type": "string", "const": "simple" }, "expression": { "type": "string" } }, "required": ["type", "expression"], "additionalProperties": false, "description": "Simple condition expression (leaf node)" }, "ParallelGroupStepMeta": { "type": "object", "properties": { "type": { "type": "string", "const": "parallel" }, "children": { "type": "array", "items": { "anyOf": [{ "$ref": "#/definitions/RpcStepMeta" }, { "$ref": "#/definitions/ScenarioStepMeta" }] }, "description": "Child steps to execute in parallel" } }, "required": ["type", "children"], "additionalProperties": false, "description": "Parallel group step metadata (Promise.all with multiple steps)" }, "FanoutStepMeta": { "type": "object", "properties": { "type": { "type": "string", "const": "fanout" }, "stepName": { "type": "string", "description": "Step name for this fanout. Optional: a fanout is not itself a cached step, and node ids are step names — borrowing a body step's name would give the loop and that step the same id, collapsing one onto the other." }, "sourceVar": { "type": "string", "description": "Source array variable name" }, "itemVar": { "type": "string", "description": "Iterator variable name" }, "mode": { "type": "string", "enum": ["parallel", "sequential"], "description": "Execution mode" }, "body": { "type": "array", "items": { "anyOf": [{ "$ref": "#/definitions/RpcStepMeta" }, { "$ref": "#/definitions/SleepStepMeta" }, { "$ref": "#/definitions/SuspendStepMeta" }, { "$ref": "#/definitions/ScenarioStepMeta" }] }, "description": "Steps to execute inline per iteration, in order" }, "timeBetween": { "type": "string", "description": "Time between iterations (sequential mode only)" } }, "required": ["type", "sourceVar", "itemVar", "mode", "body"], "additionalProperties": false, "description": "Fanout step metadata (parallel or sequential iteration)" }, "SleepStepMeta": { "type": "object", "properties": { "type": { "type": "string", "const": "sleep", "description": "Sleep step" }, "stepName": { "type": "string", "description": "Cache key (stepName from workflow.sleep)" }, "duration": { "type": ["string", "number"], "description": "Sleep duration" }, "expression": { "type": "string", "description": "Source text of a duration only known at runtime (e.g. a loop variable). The closure evaluates it, so it is legal DSL; it is kept separate from `duration` so regenerated code emits it raw rather than as a string literal, exactly as `expression` does on a set step." } }, "required": ["type", "stepName", "duration"], "additionalProperties": false, "description": "Sleep step metadata" }, "SuspendStepMeta": { "type": "object", "properties": { "type": { "type": "string", "const": "suspend" }, "reason": { "type": "string", "description": "Reason string passed to workflow.suspend() — becomes the durable step key" } }, "required": ["type", "reason"], "additionalProperties": false, "description": "Suspend step metadata (workflow.suspend())" }, "ReturnStepMeta": { "type": "object", "properties": { "type": { "type": "string", "const": "return" }, "outputs": { "type": "object", "additionalProperties": { "$ref": "#/definitions/OutputBinding" }, "description": "Output bindings" }, "spread": { "type": "array", "items": { "type": "string" }, "description": "Variables spread into the returned object (`return { ...r }`), or the sole returned variable (`return r`). Their fields are not enumerable statically, so they are recorded by name rather than expanded into `outputs`." } }, "required": ["type", "outputs"], "additionalProperties": false, "description": "Return step metadata (workflow output)" }, "OutputBinding": { "anyOf": [{ "type": "object", "properties": { "from": { "type": "string", "const": "outputVar" }, "name": { "type": "string" }, "path": { "type": "string" } }, "required": ["from", "name"], "additionalProperties": false }, { "type": "object", "properties": { "from": { "type": "string", "const": "stateVar" }, "name": { "type": "string" }, "path": { "type": "string" } }, "required": ["from", "name"], "additionalProperties": false }, { "type": "object", "properties": { "from": { "type": "string", "const": "input" }, "path": { "type": "string" } }, "required": ["from", "path"], "additionalProperties": false }, { "type": "object", "properties": { "from": { "type": "string", "const": "literal" }, "value": {} }, "required": ["from", "value"], "additionalProperties": false }, { "type": "object", "properties": { "from": { "type": "string", "const": "expression" }, "expression": { "type": "string" } }, "required": ["from", "expression"], "additionalProperties": false }], "description": "Output binding for return statements in DSL workflows" }, "InlineStepMeta": { "type": "object", "properties": { "type": { "type": "string", "const": "inline", "description": "Inline form - local execution" }, "stepName": { "type": "string", "description": "Cache key (stepName from workflow.do)" }, "description": { "type": "string", "description": "Display name" }, "options": { "$ref": "#/definitions/WorkflowStepOptions", "description": "Step options" } }, "required": ["type", "stepName"], "additionalProperties": false, "description": "Inline step metadata (legacy support)" }, "CancelStepMeta": { "type": "object", "properties": { "type": { "type": "string", "const": "cancel", "description": "Cancel step" }, "reason": { "type": "string", "description": "Optional cancellation reason" } }, "required": ["type"], "additionalProperties": false, "description": "Cancel step metadata" }, "ApprovalStepMeta": { "type": "object", "properties": { "type": { "type": "string", "const": "approval" }, "reason": { "type": "string", "description": "Reason string passed to workflow.approval() — becomes the durable step key" }, "outputVar": { "type": "string", "description": "Output variable name (if assigned)" }, "expiry": { "type": ["string", "number"], "description": "Expiry duration, when one was given" } }, "required": ["type", "reason"], "additionalProperties": false, "description": "Approval step metadata (workflow.approval())" }, "SwitchStepMeta": { "type": "object", "properties": { "type": { "type": "string", "const": "switch" }, "expression": { "type": "string", "description": "Expression being switched on" }, "cases": { "type": "array", "items": { "$ref": "#/definitions/SwitchCaseMeta" }, "description": "Case branches" }, "defaultSteps": { "type": "array", "items": { "$ref": "#/definitions/WorkflowStepMeta" }, "description": "Default case steps (optional)" } }, "required": ["type", "expression", "cases"], "additionalProperties": false, "description": "Switch step metadata (switch/case control flow)" }, "SwitchCaseMeta": { "type": "object", "properties": { "value": { "type": ["string", "number", "boolean", "null"], "description": "Case value (literal) or expression" }, "expression": { "type": "string", "description": "Case expression (for complex cases)" }, "steps": { "type": "array", "items": { "$ref": "#/definitions/WorkflowStepMeta" }, "description": "Steps to execute for this case" } }, "required": ["steps"], "additionalProperties": false, "description": "Switch case metadata" }, "FilterStepMeta": { "type": "object", "properties": { "type": { "type": "string", "const": "filter" }, "sourceVar": { "type": "string", "description": "Source array variable name" }, "itemVar": { "type": "string", "description": "Iterator variable name" }, "condition": { "$ref": "#/definitions/Condition", "description": "Filter condition" }, "outputVar": { "type": "string", "description": "Output variable name (if assigned)" } }, "required": ["type", "sourceVar", "itemVar", "condition"], "additionalProperties": false, "description": "Filter step metadata (array.filter)" }, "ArrayPredicateStepMeta": { "type": "object", "properties": { "type": { "type": "string", "const": "arrayPredicate" }, "mode": { "type": "string", "enum": ["some", "every"], "description": "Predicate mode" }, "sourceVar": { "type": "string", "description": "Source array variable name" }, "itemVar": { "type": "string", "description": "Iterator variable name" }, "condition": { "$ref": "#/definitions/Condition", "description": "Predicate condition" }, "outputVar": { "type": "string", "description": "Output variable name (if assigned)" } }, "required": ["type", "mode", "sourceVar", "itemVar", "condition"], "additionalProperties": false, "description": "Array predicate step metadata (array.some, array.every)" }, "SetStepMeta": { "type": "object", "properties": { "type": { "type": "string", "const": "set", "description": "Set step" }, "variable": { "type": "string", "description": "Variable name to set (must be in context)" }, "value": { "description": "Literal value to assign. Mutually exclusive with `expression`." }, "expression": { "type": "string", "description": "Source text of a non-literal assignment (e.g. `count + 1`). Kept separate from `value` so regenerated code can emit it raw — a string `value` is a string literal, an `expression` is code." } }, "required": ["type", "variable"], "additionalProperties": false, "description": "Set step metadata (context variable assignment)" }, "WorkflowContext": { "type": "object", "additionalProperties": { "$ref": "#/definitions/ContextVariable" } }, "ContextVariable": { "type": "object", "properties": { "type": { "type": "string", "enum": ["string", "number", "boolean", "object", "array"] }, "default": {}, "description": { "type": "string" } }, "required": ["type"], "additionalProperties": false }, "ResolvedPersona": { "type": "object", "additionalProperties": false, "properties": { "email": { "type": "string" }, "id": { "type": "string", "description": "The key it was declared under." }, "name": { "type": "string" }, "jobTitle": { "type": "string" }, "description": { "type": "string" }, "roles": { "type": "array", "items": { "type": "string" } }, "personality": { "type": "string" }, "goals": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "disposition": { "$ref": "#/definitions/VirtualUserDisposition" }, "tuning": { "$ref": "#/definitions/VirtualUserTuning" }, "fixtures": { "type": "array", "items": { "type": "string" } }, "account": { "$ref": "#/definitions/PersonaAccountMeta" }, "linkedAccounts": { "type": "object", "additionalProperties": { "$ref": "#/definitions/PersonaAccountMeta" } }, "environments": { "type": "array", "items": { "type": "string" }, "description": "Absent means \"everywhere but production\", which is resolved, not stored." }, "runnable": { "type": "boolean" }, "sourceFile": { "type": "string" } }, "required": ["email", "goals", "id", "name", "roles", "runnable", "tags"], "description": "A declared persona with its address filled in — what codegen writes and what a seed, a scenario run and a virtual-user run all read.\n\nThe address is not declared. It is derived from the persona's id and the project's persona domain, so two people can never accidentally share one and sign in as the same user row — which would silently collapse exactly the isolation scenarios a second person exists for." }, "VirtualUserDisposition": { "type": "string", "enum": ["realistic", "careless", "newcomer", "stale", "auditor", "adversarial", "accountable"], "description": "How a virtual user behaves, mechanically. A disposition changes the loop, the input generation, the memory and the oracle — anything that only changes how the user talks is persona prose (`ResolvedPersona.personality`) and does not belong here.\n\n- `realistic` — schema-first, goal-directed, plausible values (default).\n- `careless` — repeats, abandons, double-submits, boundary values.\n- `newcomer` — starts with empty memory and must discover everything.\n- `stale` — seeded from an earlier run's ids, some no longer valid.\n- `auditor` — pursues no goal; reads one truth from several places and compares.\n- `adversarial` — probes authorization and tenancy; a 2xx can be the finding.\n- `accountable` — pursues its goals for real; the only one production allows.\n\n`accountable` sits opposite `adversarial` on an intent axis — bad faith against good faith — where `careless` and `thorough` are a care axis. It is the one disposition whose actions carry consequences: no oracle, no rollback, and every call attributed to the persona in the audit log like anyone else's." }, "VirtualUserTuning": { "type": "object", "properties": { "moves": { "type": "object", "properties": { "continue": { "type": "number" }, "suspend": { "type": "number" }, "resume": { "type": "number" }, "abandon": { "type": "number" } }, "additionalProperties": false, "description": "Relative weights for the scheduler's moves. Merged over the profile's." }, "temperature": { "type": "number" }, "repeatRate": { "type": "number" }, "reReadRate": { "type": "number" }, "emptyMemory": { "type": "boolean" }, "readOnly": { "type": "boolean" }, "invertedOracle": { "type": "boolean" }, "instructions": { "type": "string", "description": "Extra behaviour, appended to the disposition's own instructions." } }, "additionalProperties": false, "description": "Per-user overrides for a disposition's dials.\n\nThe six profiles below are starting points, not laws — the weights are a considered guess about how people behave, and your product is allowed to know better. A user that declares `disposition: 'careless'` with a higher `repeatRate` is still a careless user; it is the same behaviour tuned to a product where double-submits actually happen.\n\n`instructions` is the one field that appends rather than replaces. Everything else is a number the engine reads, so overriding it changes the run and nothing else; instructions are the model's sense of who it is, and letting a declaration replace them wholesale is how you end up with a `careless` user that is not careless — which makes the name, and every run labelled with it, a lie." }, "PersonaAccountMeta": { "type": "object", "properties": { "provider": { "type": "string" } }, "additionalProperties": false }, "SystemRoleDefinitionsMeta": { "type": "object", "additionalProperties": { "$ref": "#/definitions/SystemRoleDefinitionMeta" } }, "SystemRoleDefinitionMeta": { "type": "object", "properties": { "name": { "type": "string" }, "displayName": { "type": "string" }, "description": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "sourceFile": { "type": "string" } }, "required": ["name", "scopes"], "additionalProperties": false }, "FeaturesMeta": { "type": "object", "additionalProperties": { "$ref": "#/definitions/FeatureMeta" } }, "FeatureMeta": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "entries": { "type": "array", "items": { "$ref": "#/definitions/FeatureMetaEntry" } }, "unresolvedEntries": { "type": "number" }, "hasBefore": { "type": "boolean" }, "hasAfter": { "type": "boolean" } }, "required": ["id", "name", "tags", "entries", "unresolvedEntries", "hasBefore", "hasAfter"], "additionalProperties": false }, "FeatureMetaEntry": { "type": "object", "properties": { "scenario": { "type": "string" }, "data": {} }, "required": ["scenario"], "additionalProperties": false }, "TriggerMeta": { "type": "object", "properties": { "pikkuFuncId": { "type": "string" }, "name": { "type": "string" }, "summary": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "middleware": { "type": "array", "items": { "$ref": "#/definitions/MiddlewareMetadata" } }, "permissions": { "type": "array", "items": { "$ref": "#/definitions/PermissionMetadata" } } }, "required": ["pikkuFuncId", "name"], "additionalProperties": false }, "TriggerSourceMeta": { "type": "object", "properties": { "name": { "type": "string" }, "pikkuFuncId": { "type": "string" }, "packageName": { "type": "string" }, "summary": { "type": "string" }, "description": { "type": "string" } }, "required": ["name", "pikkuFuncId"], "additionalProperties": false }, "MiddlewareGroupsMeta": { "type": "object", "properties": { "definitions": { "type": "object", "additionalProperties": { "$ref": "#/definitions/MiddlewareDefinitionMeta" } }, "instances": { "type": "object", "additionalProperties": { "$ref": "#/definitions/MiddlewareInstanceMeta" } }, "httpGroups": { "type": "object", "additionalProperties": { "$ref": "#/definitions/GroupMeta" } }, "tagGroups": { "type": "object", "additionalProperties": { "$ref": "#/definitions/GroupMeta" } } }, "required": ["definitions", "instances", "httpGroups", "tagGroups"], "additionalProperties": false }, "MiddlewareDefinitionMeta": { "type": "object", "properties": { "services": { "type": "object", "properties": { "optimized": { "type": "boolean" }, "services": { "type": "array", "items": { "type": "string" } } }, "required": ["optimized", "services"], "additionalProperties": false }, "sourceFile": { "type": "string" }, "position": { "type": "number" }, "exportedName": { "type": ["string", "null"] }, "factory": { "type": "boolean" }, "name": { "type": "string" }, "description": { "type": "string" }, "package": { "type": "string" } }, "required": ["services", "sourceFile", "position", "exportedName"], "additionalProperties": false }, "MiddlewareInstanceMeta": { "type": "object", "properties": { "definitionId": { "type": "string" }, "sourceFile": { "type": "string" }, "position": { "type": "number" }, "isFactoryCall": { "type": "boolean" } }, "required": ["definitionId", "sourceFile", "position", "isFactoryCall"], "additionalProperties": false }, "GroupMeta": { "type": "object", "properties": { "exportName": { "type": ["string", "null"] }, "sourceFile": { "type": "string" }, "position": { "type": "number" }, "services": { "type": "object", "properties": { "optimized": { "type": "boolean" }, "services": { "type": "array", "items": { "type": "string" } } }, "required": ["optimized", "services"], "additionalProperties": false }, "count": { "type": "number" }, "instanceIds": { "type": "array", "items": { "type": "string" } }, "isFactory": { "type": "boolean" } }, "required": ["exportName", "sourceFile", "position", "services", "count", "instanceIds", "isFactory"], "additionalProperties": false }, "PermissionsGroupsMeta": { "type": "object", "properties": { "definitions": { "type": "object", "additionalProperties": { "$ref": "#/definitions/PermissionDefinitionMeta" } } }, "required": ["definitions"], "additionalProperties": false }, "PermissionDefinitionMeta": { "type": "object", "properties": { "services": { "type": "object", "properties": { "optimized": { "type": "boolean" }, "services": { "type": "array", "items": { "type": "string" } } }, "required": ["optimized", "services"], "additionalProperties": false }, "sourceFile": { "type": "string" }, "position": { "type": "number" }, "exportedName": { "type": ["string", "null"] }, "factory": { "type": "boolean" }, "name": { "type": "string" }, "description": { "type": "string" } }, "required": ["services", "sourceFile", "position", "exportedName"], "additionalProperties": false }, "AgentsMeta": { "$ref": "#/definitions/AIAgentMeta" }, "AIAgentMeta": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": false, "properties": { "tools": { "type": "array", "items": { "type": "string" } }, "agents": { "type": "array", "items": { "type": "string" } }, "workflows": { "type": "array", "items": { "type": "string" } }, "inputSchema": { "type": ["string", "null"] }, "outputSchema": { "type": ["string", "null"] }, "workingMemorySchema": { "type": ["string", "null"] }, "middleware": { "type": "array", "items": { "$ref": "#/definitions/MiddlewareMetadata" } }, "channelMiddleware": { "type": "array", "items": { "$ref": "#/definitions/MiddlewareMetadata" } }, "aiMiddleware": { "type": "array", "items": { "$ref": "#/definitions/MiddlewareMetadata" } }, "permissions": { "type": "array", "items": { "$ref": "#/definitions/PermissionMetadata" } }, "sourceFile": { "type": "string" }, "exportedName": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "summary": { "type": "string" }, "errors": { "type": "array", "items": { "type": "string" } }, "role": { "type": "string", "description": "The three fields below are the system prompt. `buildInstructions` joins whichever are set with a blank line, always in this order — role, then personality, then goal — and appends the tool-usage rules if the agent has tools. Nothing checks them against each other: the split is there to keep a prompt legible, and text put in the wrong one still reaches the model.\n\nWho the agent is. 'You are a support engineer triaging inbound bugs.'" }, "personality": { "type": "string", "description": "How it should sound: tone, vocabulary, how much it says at a time." }, "goal": { "type": "string", "description": "What it is for — the only one of the three that is required." }, "model": { "type": "string" }, "temperature": { "type": "number" }, "sessionScope": { "$ref": "#/definitions/SessionScope", "description": "Ownership/partitioning of this agent's threads and runs. Defaults to `'user'`." }, "agentMode": { "type": "string", "enum": ["delegate", "supervise"] }, "memory": { "$ref": "#/definitions/AIAgentMemoryConfig" }, "maxSteps": { "type": "number" }, "toolChoice": { "type": "string", "enum": ["auto", "required", "none"] }, "providerOptions": { "$ref": "#/definitions/AIProviderOptions", "description": "Per-provider model settings, keyed by provider id and passed through untouched — for anything only one vendor offers, which the fields above deliberately do not try to unify.\n\n`{ openai: { reasoningEffort: 'minimal' } }` is the one that matters for voice: on gpt-5-mini it measured 0.9s to first token against 2.5s at the default, and a spoken reply is waited through rather than skimmed." }, "tags": { "type": "array", "items": { "type": "string" } }, "prepareStep": { "$comment": "(ctx: {\n stepNumber: number;\n messages: AIMessage[];\n tools: AIAgentToolDef[];\n toolChoice: 'auto' \| 'required' \| 'none';\n model: string;\n stop: () => void;\n }) => void \| Promise<void>", "type": "object", "properties": { "namedArgs": { "type": "object", "properties": { "ctx": { "type": "object", "properties": { "stepNumber": { "type": "number" }, "messages": { "type": "array", "items": { "$ref": "#/definitions/AIMessage" } }, "tools": { "type": "array", "items": { "$ref": "#/definitions/AIAgentToolDef" } }, "toolChoice": { "type": "string", "enum": ["auto", "required", "none"] }, "model": { "type": "string" }, "stop": { "$comment": "() => void" } }, "required": ["stepNumber", "messages", "tools", "toolChoice", "model", "stop"], "additionalProperties": false } }, "required": ["ctx"], "additionalProperties": false } } }, "auth": { "type": "boolean", "description": "Whether a session is required to run this agent. Defaults to `false`, since agents are commonly invoked from an already-authenticated `pikkuFunc` or from genuinely sessionless contexts (crons, queue workers). Set `true` to require a session at the agent itself. `scopes` and `permissions` are enforced either way." }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "Scopes the session must hold to run this agent. All of them are required (AND), and they are checked before `permissions` — unlike permissions, which OR together, a scope can only narrow access.\n\nNarrowed to the generated `ScopeId` union in a project's own `pikku-types.gen.ts`, so an undeclared scope is a compile error." } }, "required": ["description", "goal", "inputSchema", "model", "name", "outputSchema", "workingMemorySchema"] } }, "SessionScope": { "type": "string", "enum": ["user", "org"], "description": "How an agent's threads/runs are owned and partitioned.\n- `'user'` (default): owner is the authenticated `session.userId`; the caller's `resourceId` becomes a sub-partition within that user (`userId:resourceId`).\n- `'org'`: owner is the authenticated `session.orgId` (`orgId:resourceId`), so threads are shared across everyone in the org. Requires a session with an org (e.g. Better Auth's `organization` plugin) — otherwise access is denied.\n\nThe trusted principal is always the prefix, so a client-supplied `resourceId` can sub-divide within the caller's own boundary but can never widen access to another user's or org's threads." }, "AIAgentMemoryConfig": { "type": "object", "properties": { "storage": { "type": "string" }, "vector": { "type": "string" }, "embedder": { "type": "string" }, "lastMessages": { "type": "number" }, "workingMemory": {} }, "additionalProperties": false }, "AIProviderOptions": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": {} } }, "AIMessage": { "type": "object", "properties": { "id": { "type": "string" }, "role": { "type": "string", "enum": ["system", "user", "assistant", "tool"] }, "content": { "anyOf": [{ "type": "string" }, { "type": "array", "items": { "$ref": "#/definitions/AIContentPart" } }] }, "toolCalls": { "type": "array", "items": { "$ref": "#/definitions/AIToolCall" } }, "toolResults": { "type": "array", "items": { "$ref": "#/definitions/AIToolResult" } }, "reasoningContent": { "type": "string" }, "interrupted": { "type": "boolean", "description": "Set on an assistant message whose generation was cut short by an interrupt — the text is a mid-sentence fragment, not a reply. Carried into the next turn's context so the model can see it said only this much before being talked over, and decide for itself whether to resume, restate or move on. Storage that drops unknown fields loses the marker but keeps the fragment, which degrades to a truncated reply." }, "undelivered": { "type": "boolean", "description": "Set on a tool message whose result arrived after the run was interrupted, so the model never got to describe it. The work happened; only the reply about it was lost. It is ordinary thread context on the next turn — the model raises it unprompted (\"that deploy did go through\") rather than the result being silently dropped or replayed as a fresh tool call." }, "createdAt": { "type": "string", "format": "date-time" } }, "required": ["id", "role", "createdAt"], "additionalProperties": false }, "AIContentPart": { "anyOf": [{ "type": "object", "properties": { "type": { "type": "string", "const": "text" }, "text": { "type": "string" } }, "required": ["type", "text"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "image" }, "data": { "type": "string" }, "url": { "type": "string" }, "mediaType": { "type": "string" } }, "required": ["type"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "file" }, "data": { "type": "string" }, "url": { "type": "string" }, "mediaType": { "type": "string" }, "filename": { "type": "string" } }, "required": ["type", "mediaType"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "data" }, "name": { "type": "string" }, "data": {} }, "required": ["type", "name", "data"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "generative-ui" }, "spec": {} }, "required": ["type", "spec"], "additionalProperties": false }] }, "AIToolCall": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "args": { "type": "object", "additionalProperties": {} } }, "required": ["id", "name", "args"], "additionalProperties": false }, "AIToolResult": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "result": { "type": "string" } }, "required": ["id", "name", "result"], "additionalProperties": false }, "AIAgentToolDef": { "type": "object", "properties": { "needsApproval": { "type": "boolean" }, "approvalDescriptionFn": { "$comment": "(input: unknown) => Promise<string> \| string", "type": "object", "properties": { "namedArgs": { "type": "object", "properties": { "input": {} }, "required": ["input"], "additionalProperties": false } } }, "name": { "type": "string" }, "description": { "type": "string" }, "inputSchema": { "type": "object", "additionalProperties": {} }, "execute": { "$comment": "(input: unknown) => Promise<unknown>", "type": "object", "properties": { "namedArgs": { "type": "object", "properties": { "input": {} }, "required": ["input"], "additionalProperties": false } } }, "readonly": { "type": "boolean", "description": "Mirrors the pikku function's `readonly` flag. A read that gets interrupted is discarded rather than reported: nothing changed, and by the next turn the data may be stale anyway — re-reading is cheaper than explaining a result the user never asked to hear about." }, "forwardsApproval": { "type": "boolean", "description": "Set only by the framework on sub-agent delegating tools. Such a tool may legitimately return an `__approvalRequired` marker to forward a nested sub-agent approval. The marker is honored ONLY from a tool with this flag — a plain tool's output (which an attacker may influence) can never forge an approval request. See `checkForApprovals`." } }, "required": ["name", "description", "inputSchema", "execute"], "additionalProperties": false, "description": "`ApprovalPolicy` is shared with channel capabilities, but `Partial` here: absent `needsApproval` means \"do not ask\", which is safe because a tool is written by whoever runs the server it executes on. A capability runs on someone else's machine, so it requires the field instead." }, "EmailsMeta": { "type": "object", "properties": { "src": { "type": "string" }, "themeHash": { "type": "string" }, "templates": { "type": "object", "additionalProperties": { "$ref": "#/definitions/EmailTemplateMeta" } } }, "required": ["src", "themeHash", "templates"], "additionalProperties": false }, "EmailTemplateMeta": { "type": "object", "properties": { "variables": { "type": "array", "items": { "type": "string" } }, "hasHtml": { "type": "boolean" }, "hasSubject": { "type": "boolean" }, "hasText": { "type": "boolean" }, "locales": { "type": "object", "additionalProperties": { "$ref": "#/definitions/EmailTemplateLocaleMeta" } } }, "required": ["variables", "hasHtml", "hasSubject", "hasText", "locales"], "additionalProperties": false }, "EmailTemplateLocaleMeta": { "type": "object", "properties": { "contentHash": { "type": "string" }, "htmlHash": { "type": "string" }, "subjectHash": { "type": "string" }, "textHash": { "type": "string" } }, "required": ["contentHash", "htmlHash", "subjectHash", "textHash"], "additionalProperties": false }, "FunctionUsedBy": { "type": "object", "properties": { "transports": { "type": "array", "items": { "$ref": "#/definitions/WiringRef" } }, "jobs": { "type": "array", "items": { "$ref": "#/definitions/WiringRef" } }, "workflows": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": ["id", "name"], "additionalProperties": false } } }, "required": ["transports", "jobs", "workflows"], "additionalProperties": false }, "WiringRef": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" } }, "required": ["type", "id", "name"], "additionalProperties": false }, "MetaCounts": { "type": "object", "properties": { "functions": { "type": "number" }, "workflows": { "type": "number" }, "httpRoutes": { "type": "number" }, "channels": { "type": "number" }, "mcpTools": { "type": "number" }, "gateways": { "type": "number" }, "schedulers": { "type": "number" }, "queues": { "type": "number" }, "cliCommands": { "type": "number" }, "rpcMethods": { "type": "number" }, "triggers": { "type": "number" }, "triggerSources": { "type": "number" }, "agents": { "type": "number" }, "emails": { "type": "number" }, "secrets": { "type": "number" }, "variables": { "type": "number" } }, "required": ["functions", "workflows", "httpRoutes", "channels", "mcpTools", "gateways", "schedulers", "queues", "cliCommands", "rpcMethods", "triggers", "triggerSources", "agents", "emails", "secrets", "variables"], "additionalProperties": false } } }