@plurnk/plurnk-contracts 1.24.0 → 1.26.0

package/dist/src/types.generated.d.ts

@@ -149,73 +149,17 @@ export interface MimetypeDisplayCapability {
     mimetype: string;
     display: CapabilityDisplay;
 }
-export interface CapabilityDescriptor {
-    /**
-     * An operation keyword, or a runtime tag: an execution's operation is its runtime.
-     */
-    operation: "FIND" | "READ" | "EDIT" | "COPY" | "MOVE" | "SEND" | "BARE" | "WORK" | "FORK" | "KILL" | Lowercase<string>;
-    scheme?: string;
-    runtime?: string;
-    tool?: string;
-    access: ("observe" | "mutate" | "execute" | "interact" | "control");
-    traits: string[];
-}
-export interface CapabilityPolicy {
-    only?: CapabilitySelector[];
-    deny?: CapabilitySelector[];
-}
-/**
- * One exact, conjunctive selector over a routed PLURNK capability demand. Omitted fields are wildcards; at least one field is required.
- */
-export interface CapabilitySelector {
-    /**
-     * An operation keyword, or a runtime tag: an execution's operation is its runtime.
-     */
-    operation?: "FIND" | "READ" | "EDIT" | "COPY" | "MOVE" | "SEND" | "BARE" | "WORK" | "FORK" | "KILL" | Lowercase<string>;
-    scheme?: string;
-    runtime?: string;
-    tool?: string;
-    access?: ("observe" | "mutate" | "execute" | "interact" | "control");
-    /**
-     * @minItems 1
-     */
-    traits?: [string, ...(string)[]];
-}
-export interface CapabilityProjection {
-    service: CapabilityPolicy;
-    workspace: CapabilityPolicy;
-    effective: CapabilityPolicy;
-}
-/**
- * One purely subtractive capability-policy layer. Deny wins; when only is present, a demand must match at least one selector.
- */
-export interface ClientInteractionProjection {
-    interactionId: number;
+export type ApplicationOperationEvent = {
     workerId: number;
     loopId: number;
     turnId: number;
-    request: ClientInteractionRequest;
-}
-/**
- * A runtime-neutral request for one client-owned interaction. The owner supplies the standard tool presentation and response contract; protocol-private continuation state is excluded.
- */
-export interface ClientInteractionRequest {
-    toolName: string;
-    arguments: {
-        [k: string]: unknown;
-    };
-    message?: string;
-    responseSchema: {
-        [k: string]: unknown;
-    };
-}
-export type ClientInteractionResolution = ({
-    status: "resolved";
-    payload?: unknown;
-} | {
-    status: "cancelled";
-});
-export type ClientStatement = (PlurnkStatement | LookStatement);
+    sequence: number;
+    origin: ("model" | "client" | "_plurnk" | "plugin");
+    projectRoot: (string | null);
+    statement: PlurnkStatement;
+    phase: ("started" | "settled");
+    result?: OperationResult;
+};
 /**
  * The parsed AST union for one protocol statement, discriminated by `op`. Every variant has fixed signal, target, metadata, lineMarker, aside, body, and source-position fields, and the text and log operations add a matcher lifted from the `pattern` option; operation-specific schemas constrain their types. A null field records an omitted tolerated slot and does not satisfy runtime requirements by itself.
  */
@@ -228,11 +172,28 @@ export type ParsedPath = (LocalPath | UrlPath);
  * Parsed single-line body of a matcher-bearing statement, discriminated on `dialect`. The dialect is determined by the body's leading characters (`//` xpath, `/` regex, `$` jsonpath, `~` full-text, `&` graph, else glob). The regex variant carries pattern and flags split out of the `/pattern/flags` literal; every variant remains JSON-serializable.
  */
 export type MatcherBody = (XPathBody | RegexBody | JsonPathBody | FtsBody | GraphBody | GlobBody);
-export type AsideOrNull = (string | null);
-export type SchemeMetadataOrNull = (string[] | null);
-export type PathOrNull = (ParsedPath | null);
-export type TextLineMarkerOrNull = (TextLineMarker | null);
-export type MatcherBodyOrNull = (MatcherBody | null);
+/**
+ * Universal PLURNK operation result. Producer-owned metadata is open, but failures always carry one RFC 9457 Problem Details object and never a parallel error field.
+ */
+export type OperationResult = ({
+    status: number;
+    problem?: ProblemDetails;
+    range?: RangeExtent;
+    error?: never;
+    [k: string]: unknown;
+} & {
+    status?: number;
+});
+/**
+ * @minItems 2
+ * @maxItems 2
+ */
+export type RequestedRange = [number, number];
+/**
+ * @minItems 2
+ * @maxItems 2
+ */
+export type ReturnedRange = [number, number];
 export interface FindStatement {
     op: "FIND";
     aside: (string | null);
@@ -522,39 +483,6 @@ export interface NoteStatement {
     body: (string | null);
     position: Position;
 }
-export interface LookStatement {
-    op: "LOOK";
-    aside: AsideOrNull;
-    metadata: SchemeMetadataOrNull;
-    target: PathOrNull;
-    lineMarker: TextLineMarkerOrNull;
-    body: MatcherBodyOrNull;
-    position: Position;
-}
-export type Effort = ("off" | "adaptive" | "low" | "medium" | "high" | "xhigh" | "max");
-export type EntryReadResult = ({
-    status: 200;
-    entry: ClientEntry;
-} | {
-    status: number;
-    problem: ProblemDetails;
-    entry: null;
-});
-export interface ClientEntry {
-    entryId: number;
-    target: string;
-    channels: {
-        [k: string]: ClientEntryChannel;
-    };
-}
-export interface ClientEntryChannel {
-    content: string;
-    contentOffset: number;
-    contentLength: number;
-    mimetype: string;
-    weight: number;
-    state: ("static" | "active" | "closed" | "errored");
-}
 /**
  * PLURNK operation failure using RFC 9457 Problem Details. Extension members are permitted so an owning boundary can add structured causal and recovery facts without inventing a second error envelope.
  */
@@ -593,6 +521,126 @@ export interface ProblemDetails {
     retryable?: boolean;
     [k: string]: unknown;
 }
+/**
+ * A compact projection of one line or ordered-result selection. Requested and returned positions are inclusive; total is the complete available cardinality.
+ */
+export interface RangeExtent {
+    unit: ("line" | "result" | "resource" | "matchLocation" | "byte");
+    total: number;
+    requested: RequestedRange;
+    returned?: ReturnedRange;
+}
+export interface CapabilityDescriptor {
+    /**
+     * An operation keyword, or a runtime tag: an execution's operation is its runtime.
+     */
+    operation: "FIND" | "READ" | "EDIT" | "COPY" | "MOVE" | "SEND" | "BARE" | "WORK" | "FORK" | "KILL" | Lowercase<string>;
+    scheme?: string;
+    runtime?: string;
+    tool?: string;
+    access: ("observe" | "mutate" | "execute" | "interact" | "control");
+    traits: string[];
+}
+export interface CapabilityPolicy {
+    only?: CapabilitySelector[];
+    deny?: CapabilitySelector[];
+}
+/**
+ * One exact, conjunctive selector over a routed PLURNK capability demand. Omitted fields are wildcards; at least one field is required.
+ */
+export interface CapabilitySelector {
+    /**
+     * An operation keyword, or a runtime tag: an execution's operation is its runtime.
+     */
+    operation?: "FIND" | "READ" | "EDIT" | "COPY" | "MOVE" | "SEND" | "BARE" | "WORK" | "FORK" | "KILL" | Lowercase<string>;
+    scheme?: string;
+    runtime?: string;
+    tool?: string;
+    access?: ("observe" | "mutate" | "execute" | "interact" | "control");
+    /**
+     * @minItems 1
+     */
+    traits?: [string, ...(string)[]];
+}
+export interface CapabilityProjection {
+    service: CapabilityPolicy;
+    workspace: CapabilityPolicy;
+    effective: CapabilityPolicy;
+}
+/**
+ * One purely subtractive capability-policy layer. Deny wins; when only is present, a demand must match at least one selector.
+ */
+export interface ClientInteractionProjection {
+    interactionId: number;
+    workerId: number;
+    loopId: number;
+    turnId: number;
+    request: ClientInteractionRequest;
+}
+/**
+ * A runtime-neutral request for one client-owned interaction. The owner supplies the standard tool presentation and response contract; protocol-private continuation state is excluded.
+ */
+export interface ClientInteractionRequest {
+    toolName: string;
+    arguments: {
+        [k: string]: unknown;
+    };
+    message?: string;
+    responseSchema: {
+        [k: string]: unknown;
+    };
+}
+export type ClientInteractionResolution = ({
+    status: "resolved";
+    payload?: unknown;
+} | {
+    status: "cancelled";
+});
+export type ClientStatement = (PlurnkStatement | LookStatement);
+/**
+ * The parsed AST union for one protocol statement, discriminated by `op`. Every variant has fixed signal, target, metadata, lineMarker, aside, body, and source-position fields, and the text and log operations add a matcher lifted from the `pattern` option; operation-specific schemas constrain their types. A null field records an omitted tolerated slot and does not satisfy runtime requirements by itself.
+ */
+export type AsideOrNull = (string | null);
+export type SchemeMetadataOrNull = (string[] | null);
+export type PathOrNull = (ParsedPath | null);
+export type TextLineMarkerOrNull = (TextLineMarker | null);
+export type MatcherBodyOrNull = (MatcherBody | null);
+export interface LookStatement {
+    op: "LOOK";
+    aside: AsideOrNull;
+    metadata: SchemeMetadataOrNull;
+    target: PathOrNull;
+    lineMarker: TextLineMarkerOrNull;
+    body: MatcherBodyOrNull;
+    position: Position;
+}
+export type Effort = ("off" | "adaptive" | "low" | "medium" | "high" | "xhigh" | "max");
+export type EntryReadResult = ({
+    status: 200;
+    entry: ClientEntry;
+} | {
+    status: number;
+    problem: ProblemDetails;
+    entry: null;
+});
+export interface ClientEntry {
+    entryId: number;
+    target: string;
+    channels: {
+        [k: string]: ClientEntryChannel;
+    };
+}
+export interface ClientEntryChannel {
+    content: string;
+    contentOffset: number;
+    contentLength: number;
+    mimetype: string;
+    weight: number;
+    state: ("static" | "active" | "closed" | "errored");
+}
+/**
+ * PLURNK operation failure using RFC 9457 Problem Details. Extension members are permitted so an owning boundary can add structured causal and recovery facts without inventing a second error envelope.
+ */
 export interface FunctionalityCandidate {
     /**
      * The alias the candidate would take if added; a suggestion, never authority.
@@ -603,11 +651,15 @@ export interface FunctionalityCandidate {
      * The exact family definition, conforming to the family's definition schema.
      */
     definition: {};
-    provenance: {
-        kind: string;
-        source: string;
-        reference?: string;
-    };
+    provenance: FunctionalityProvenance;
+}
+/**
+ * The input supplying a definition or discovery candidate, separate from ownership, preparation and authority.
+ */
+export interface FunctionalityProvenance {
+    kind: string;
+    source: string;
+    reference?: string;
 }
 export type FunctionalityDefinitionState = {
     alias: string;
@@ -616,10 +668,11 @@ export type FunctionalityDefinitionState = {
      */
     origin: ("service" | "workspace" | "worker");
     /**
-     * disabled: available, model-invisible. active: enabled and prepared. unavailable: enabled but preparation has an exact Problem. authorization-required: enabled and awaiting a protocol continuation.
+     * disabled: available, model-invisible. dormant: enabled without a resident publication. active: enabled and prepared. unavailable: enabled but preparation has an exact Problem. authorization-required: enabled and awaiting a protocol continuation.
      */
-    state: ("disabled" | "active" | "unavailable" | "authorization-required");
+    state: ("disabled" | "dormant" | "active" | "unavailable" | "authorization-required");
     definition?: {};
+    provenance?: FunctionalityProvenance;
     /**
      * The Worker this entry was copied from when this Worker was created (WORK or FORK), preserved across generations until this Worker changes the entry. Absent for an entry this Worker set itself. Worker-scoped families only.
      */
@@ -634,13 +687,13 @@ export type FunctionalityDefinitionState = {
     };
 };
 /**
- * PLURNK operation failure using RFC 9457 Problem Details. Extension members are permitted so an owning boundary can add structured causal and recovery facts without inventing a second error envelope.
+ * The winning configuration input, when supplied by a source reader. Independent of origin and readiness; absent for locally owned definitions or host-provided resources without a configuration input.
  */
 export interface FunctionalityDiscoverQuery {
     query?: string;
     source?: string;
     /**
-     * Caller-supplied configuration material the family interprets as candidates (a client's own PLURNK_MCP_* environment, a local directory list). It contributes candidates with client-configuration provenance; it never becomes durable authority.
+     * Caller-supplied configuration material the family interprets as candidates (a client's own PLURNK_A2A_* environment, a local directory list). It contributes candidates with client-configuration provenance; it never becomes durable authority.
      */
     configuration?: {};
 }
@@ -656,7 +709,7 @@ export interface FunctionalityListResult {
     definitions: FunctionalityDefinitionState[];
 }
 /**
- * PLURNK operation failure using RFC 9457 Problem Details. Extension members are permitted so an owning boundary can add structured causal and recovery facts without inventing a second error envelope.
+ * The winning configuration input, when supplied by a source reader. Independent of origin and readiness; absent for locally owned definitions or host-provided resources without a configuration input.
  */
 export interface FunctionalityMutationResult {
     status: (200 | 201 | 202);
@@ -666,8 +719,14 @@ export interface FunctionalityMutationResult {
     removed?: true;
 }
 /**
- * PLURNK operation failure using RFC 9457 Problem Details. Extension members are permitted so an owning boundary can add structured causal and recovery facts without inventing a second error envelope.
+ * The winning configuration input, when supplied by a source reader. Independent of origin and readiness; absent for locally owned definitions or host-provided resources without a configuration input.
  */
+export interface FunctionalityPreparationActivity {
+    family: string;
+    alias: (string | null);
+    phase: ("preparing" | "publishing");
+    since: string;
+}
 export interface LoopPolicy {
     /**
      * review holds a proposal for a client's answer; accept applies it and reject refuses it inside the loop.
@@ -688,98 +747,7 @@ export interface LoopPolicyRequest {
      */
     attended?: boolean;
 }
-export interface McpConfigurationOverlay {
-    [k: string]: string;
-}
-export type McpServerDefinition = {
-    /**
-     * Server alias: the runtime tag whose fence invokes it, and its resource scheme.
-     */
-    name: string;
-    /**
-     * stdio launches a local command; http connects to a remote MCP endpoint.
-     */
-    transport: ("stdio" | "http");
-    /**
-     * Executable to launch for stdio; arguments belong in args.
-     */
-    command?: string;
-    /**
-     * Arguments passed to the stdio executable in order.
-     */
-    args?: string[];
-    /**
-     * Working directory for the stdio process.
-     */
-    cwd?: string;
-    /**
-     * Environment overrides for the stdio process; values may reference ${ENV_NAME}.
-     */
-    env?: {
-        [k: string]: string;
-    };
-    /**
-     * HTTP MCP endpoint URL.
-     */
-    url?: string;
-    /**
-     * HTTP request headers; values may reference ${ENV_NAME}. Authorization cannot also be configured here when authorization is set.
-     */
-    headers?: {
-        [k: string]: string;
-    };
-    /**
-     * HTTP authentication. Secret fields reference the operator environment rather than embedding credentials.
-     */
-    authorization?: ({
-        type: "bearer";
-        token: EnvironmentReference;
-    } | {
-        type: "oauth";
-        redirectUrl: string;
-        clientMetadataUrl: string;
-        scope?: string;
-    } | {
-        type: "oauth";
-        redirectUrl: string;
-        clientId: string;
-        clientSecret: EnvironmentReference;
-        scope?: string;
-    } | {
-        type: "oauth";
-        redirectUrl: string;
-        scope?: string;
-    } | {
-        type: "client-credentials";
-        clientId: string;
-        clientSecret: EnvironmentReference;
-        scope?: string;
-        issuer?: string;
-    });
-    /**
-     * Exact enabled tool names; omitted enables all tools, an empty array enables none.
-     */
-    tools?: string[];
-    /**
-     * Exact tool names the operator designates as read effects rather than host effects requiring proposal review.
-     */
-    read?: string[];
-};
-/**
- * An operator environment variable reference such as ${GITEA_TOKEN}, never a literal secret.
- */
-export type EnvironmentReference = string;
-export type McpServerArguments = string[];
-/**
- * HTTP authentication. Secret fields reference the operator environment rather than embedding credentials.
- */
-export type McpServerAuthorization = ({
-    type: "bearer";
-    /**
-     * An operator environment variable reference such as ${GITEA_TOKEN}, never a literal secret.
-     */
-    token: string;
-} | {
+export type McpOAuth = ({
     type: "oauth";
     redirectUrl: string;
     clientMetadataUrl: string;
@@ -788,10 +756,7 @@ export type McpServerAuthorization = ({
     type: "oauth";
     redirectUrl: string;
     clientId: string;
-    /**
-     * An operator environment variable reference such as ${GITEA_TOKEN}, never a literal secret.
-     */
-    clientSecret: string;
+    clientSecret: EnvironmentReference;
     scope?: string;
 } | {
     type: "oauth";
@@ -800,44 +765,74 @@ export type McpServerAuthorization = ({
 } | {
     type: "client-credentials";
     clientId: string;
-    /**
-     * An operator environment variable reference such as ${GITEA_TOKEN}, never a literal secret.
-     */
-    clientSecret: string;
+    clientSecret: EnvironmentReference;
     scope?: string;
     issuer?: string;
 });
 /**
- * Exact enabled tool names; omitted enables all tools, an empty array enables none.
+ * An operator environment variable reference such as ${GITEA_TOKEN}, never a literal secret.
+ */
+export type EnvironmentReference = string;
+export type McpServerDefinition = (McpStdioServerDefinition | McpStreamableHttpServerDefinition);
+/**
+ * The server's alias: the runtime tag whose fence invokes it and its resource scheme.
  */
-export type McpServerToolNames = string[];
+export type McpServerName = string;
 /**
- * Exact tool names the operator designates as read effects rather than host effects requiring proposal review.
+ * This endpoint's bearer or OAuth configuration. Secrets remain symbolic environment references.
  */
-export type McpServerReadTools = string[];
-export interface McpServerOptions {
-    args?: McpServerArguments;
+export type McpAuthorization = ({
+    type: "bearer";
     /**
-     * Working directory for the stdio process.
+     * An operator environment variable reference such as ${GITEA_TOKEN}, never a literal secret.
      */
-    cwd?: string;
-    env?: McpServerEnvironment;
-    headers?: McpServerHeaders;
-    authorization?: McpServerAuthorization;
-    tools?: McpServerToolNames;
-    read?: McpServerReadTools;
-}
+    token: string;
+} | McpOAuth);
 /**
- * Environment overrides for the stdio process; values may reference ${ENV_NAME}.
+ * OAuth configuration within one Streamable HTTP MCP server definition. Every secret is a ${NAME} reference to the operator environment.
  */
-export interface McpServerEnvironment {
-    [k: string]: string;
+export interface McpStdioServerDefinition {
+    name: McpServerName;
+    /**
+     * A local server: a subprocess speaking MCP over its standard input and output.
+     */
+    type: "stdio";
+    /**
+     * An executable name or path, without a shell. Relative paths resolve against the working directory.
+     */
+    command: string;
+    /**
+     * Exact arguments; ${NAME} environment references expand once.
+     */
+    args?: string[];
+    /**
+     * Process environment additions; ${NAME} references resolve against the workspace-composed operator environment.
+     */
+    env?: {
+        [k: string]: string;
+    };
+    /**
+     * An absolute working directory, optionally using ${NAME} references. When absent the host supplies a workspace-owned state directory outside the project.
+     */
+    cwd?: string;
 }
-/**
- * HTTP request headers; values may reference ${ENV_NAME}. Authorization cannot also be configured here when authorization is set.
- */
-export interface McpServerHeaders {
-    [k: string]: string;
+export interface McpStreamableHttpServerDefinition {
+    name: McpServerName;
+    /**
+     * A remote server: an MCP endpoint over Streamable HTTP.
+     */
+    type: "streamable-http";
+    /**
+     * The explicitly configured HTTP(S) MCP endpoint. OAuth has its own transport-security requirements.
+     */
+    url: string;
+    /**
+     * Headers sent only to this endpoint; ${NAME} references expand at connection time. Protocol-owned headers are supplied by the client. Authorization cannot also be declared as a header when authorization is configured.
+     */
+    headers?: {
+        [k: string]: string;
+    };
+    authorization?: McpAuthorization;
 }
 export interface ModelCatalogPage {
     /**
@@ -953,34 +948,6 @@ export interface LogCoordinate {
      */
     op?: string;
 }
-export type OperationResult = ({
-    status: number;
-    problem?: ProblemDetails;
-    range?: RangeExtent;
-    error?: never;
-    [k: string]: unknown;
-} & {
-    status?: number;
-});
-/**
- * @minItems 2
- * @maxItems 2
- */
-export type RequestedRange = [number, number];
-/**
- * @minItems 2
- * @maxItems 2
- */
-export type ReturnedRange = [number, number];
-/**
- * PLURNK operation failure using RFC 9457 Problem Details. Extension members are permitted so an owning boundary can add structured causal and recovery facts without inventing a second error envelope.
- */
-export interface RangeExtent {
-    unit: ("line" | "result" | "resource" | "matchLocation" | "byte");
-    total: number;
-    requested: RequestedRange;
-    returned?: ReturnedRange;
-}
 export type LineMarkerOrNull = (LineMarker | null);
 /**
  * Parsed single-line body of a matcher-bearing statement, discriminated on `dialect`. The dialect is determined by the body's leading characters (`//` xpath, `/` regex, `$` jsonpath, `~` full-text, `&` graph, else glob). The regex variant carries pattern and flags split out of the `/pattern/flags` literal; every variant remains JSON-serializable.
@@ -1108,13 +1075,17 @@ export interface SkillDefinition {
      */
     name: string;
     /**
-     * Source: project `.agents/skills`, global `~/.agents/skills`, or a service-provided resource tree. Service sources are not installer targets.
+     * A local skill folder or its SKILL.md (read in place), a Git remote, or an archive (materialized into workspace storage). Required for configured and added skills; omitted only for a host-provided tree.
      */
-    scope: ("project" | "global" | "service");
+    source?: string;
     /**
-     * The standard installer package reference (`owner/repo`, a git URL, or a local path) that provides the skill; required to add a skill that is not yet installed.
+     * The branch or tag of a git source; the remote's default branch when absent.
      */
-    source?: string;
+    ref?: string;
+    /**
+     * The commit a git source's ref named when the skill was added. The service records it; a client never supplies it.
+     */
+    commit?: string;
 }
 export interface TextRegion {
     startLine: number;