@plurnk/plurnk-contracts 1.7.0 → 1.9.0

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

@@ -1,4 +1,176 @@
+export interface A2AAgentDefinition {
+    /**
+     * The local alias: the `a2a://<name>` authority.
+     */
+    name: string;
+    /**
+     * The remote agent's absolute HTTP(S) base URL; its Agent Card is discovered at the standard well-known path unless `cardPath` names another.
+     */
+    url: string;
+    /**
+     * An absolute URL pathname replacing the standard Agent Card path.
+     */
+    cardPath?: string;
+    /**
+     * Extra request headers; values may be symbolic `${NAME}` environment references.
+     */
+    headers?: {
+        [k: string]: string;
+    };
+    authorization?: {
+        type: "bearer";
+        /**
+         * A symbolic `${NAME}` environment reference; the secret is never persisted.
+         */
+        token: string;
+    };
+}
+export interface AcpPlan {
+    /**
+     * The complete list of current plan entries.
+     */
+    entries: AcpPlanEntry[];
+    /**
+     * Metadata reserved by ACP. Consumers must not assume meanings for its keys.
+     */
+    _meta?: ({
+        [k: string]: unknown;
+    } | null);
+}
+/**
+ * One task or goal in an ACP execution plan.
+ */
+export interface AcpPlanEntry {
+    /**
+     * Human-readable description of what this task aims to accomplish.
+     */
+    content: string;
+    /**
+     * The relative importance of this task.
+     */
+    priority: ("high" | "medium" | "low");
+    /**
+     * The current execution status of this task.
+     */
+    status: ("pending" | "in_progress" | "completed");
+    /**
+     * Metadata reserved by ACP. Consumers must not assume meanings for its keys.
+     */
+    _meta?: ({
+        [k: string]: unknown;
+    } | null);
+}
+export type Disposition = ({
+    posture: ("native" | "generic");
+    dimensions: Dimensions;
+    evidence: Evidence;
+} | {
+    posture: "unsupported";
+    reason: string;
+    dimensions: Dimensions;
+    evidence: Evidence;
+});
+/**
+ * @minItems 1
+ */
+export type Dimensions = [("admission" | "projection" | "framing" | "success" | "failure" | "lifecycle" | "durability" | "composition" | "presentation"), ...(("admission" | "projection" | "framing" | "success" | "failure" | "lifecycle" | "durability" | "composition" | "presentation"))[]];
+/**
+ * @minItems 1
+ */
+export type Evidence = [string, ...(string)[]];
+/**
+ * One client's exhaustive, evidence-bearing disposition for an installed AG-UI discovery surface.
+ */
+export interface AguiClientConformance {
+    schemaVersion: 1;
+    client: string;
+    actions: {
+        [k: string]: Disposition;
+    };
+    notifications: {
+        [k: string]: Disposition;
+    };
+}
+export type Name = string;
+/**
+ * Language-neutral raw SSE and AG-UI lifecycle specimens consumed by every Plurnk client.
+ */
+export interface AguiConformanceKit {
+    schemaVersion: 1;
+    /**
+     * @minItems 1
+     */
+    transport: [TransportSpecimen, ...(TransportSpecimen)[]];
+    /**
+     * @minItems 1
+     */
+    lifecycles: [LifecycleSpecimen, ...(LifecycleSpecimen)[]];
+}
+export interface TransportSpecimen {
+    name: Name;
+    /**
+     * @minItems 1
+     */
+    chunks: [string, ...(string)[]];
+    eof: boolean;
+    expect: ({
+        events: Event[];
+    } | {
+        error: "invalid-json";
+    });
+}
+export interface Event {
+    type: string;
+    [k: string]: unknown;
+}
+export interface LifecycleSpecimen {
+    name: Name;
+    /**
+     * @minItems 1
+     */
+    events: [Event, ...(Event)[]];
+    expect: LifecycleExpectation;
+}
+export interface LifecycleExpectation {
+    completion: ("success" | "interrupt" | "error" | "dead-stream");
+    families: string[];
+    status?: number;
+    interrupt?: ("proposal" | "interaction");
+    action?: ActionExpectation;
+}
+export interface ActionExpectation {
+    kind: string;
+    ok: boolean;
+    status?: number;
+}
 export type ClientDisplayCapabilities = (SchemeDisplayCapability | MimetypeDisplayCapability)[];
+/**
+ * The complete installed AG-UI+ management and notification surface. Action and notification names are object keys so identity has one representation.
+ */
+export interface AguiDiscovery {
+    schemaVersion: 1;
+    actions: {
+        [k: string]: Action;
+    };
+    notifications: {
+        [k: string]: Notification;
+    };
+    display: ClientDisplayCapabilities;
+}
+export interface Action {
+    scope: ("worldless" | "workspace" | "worker");
+    inputSchema: JsonSchema;
+    outputSchema: JsonSchema;
+}
+/**
+ * A JSON Schema 2020-12 schema supplied by the contract owner.
+ */
+export interface JsonSchema {
+    [k: string]: unknown;
+}
+export interface Notification {
+    payloadSchema: JsonSchema;
+}
 export interface SchemeDisplayCapability {
     kind: "scheme";
     scheme: string;
@@ -40,7 +212,7 @@ export type ClientInteractionResolution = ({
 });
 export type ClientStatement = (PlurnkStatement | LookStatement | BuffStatement);
 /**
- * The parsed AST union for one protocol statement, discriminated by `op`. Every variant has fixed signal, target, lineMarker, body, suffix, and source-position fields; operation-specific schemas constrain their types. A null field records an omitted tolerated slot and does not satisfy runtime requirements by itself.
+ * The parsed AST union for one protocol statement, discriminated by `op`. Every variant has fixed signal, target, lineMarker, annotation, body, delimiter, and source-position fields; operation-specific schemas constrain their types. A null field records an omitted tolerated slot and does not satisfy runtime requirements by itself.
  */
 export type PlurnkStatement = (FindStatement | ReadStatement | OpenStatement | FoldStatement | EditStatement | CopyStatement | MoveStatement | SendStatement | ExecStatement | BareStatement | WorkStatement | ForkStatement | KillStatement | PlanStatement);
 /**
@@ -51,6 +223,11 @@ export type ParsedPath = (LocalPath | UrlPath);
  * Parsed body of a FIND/OPEN/FOLD statement, discriminated on `dialect`. The dialect is determined by the body's leading characters (`//` xpath, `/` regex, `$` jsonpath, `~` semantic, `@` 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 | SemanticBody | GraphBody | GlobBody);
+/**
+ * Plurnk's complete model-native working-memory Plan entries.
+ */
+export type Plan = PlanEntry[];
+export type AnnotationOrNull = (string | null);
 export type TagSignal = (string[] | null);
 export type PathOrNull = (ParsedPath | null);
 export type TextLineMarkerOrNull = (TextLineMarker | null);
@@ -58,7 +235,8 @@ export type MatcherBodyOrNull = (MatcherBody | null);
 export type LineMarkerOrNull = (LineMarker | null);
 export interface FindStatement {
     op: "FIND";
-    suffix: string;
+    delimiter: string;
+    annotation: (string | null);
     signal: (string[] | null);
     target: (ParsedPath | null);
     lineMarker: (LineMarker | null);
@@ -156,7 +334,8 @@ export interface Position {
 }
 export interface ReadStatement {
     op: "READ";
-    suffix: string;
+    delimiter: string;
+    annotation: (string | null);
     signal: (string[] | null);
     target: (ParsedPath | null);
     lineMarker: (TextLineMarker | null);
@@ -174,25 +353,28 @@ export interface TextLineMarker {
 }
 export interface OpenStatement {
     op: "OPEN";
-    suffix: string;
+    delimiter: string;
+    annotation: (string | null);
     signal: (string[] | null);
     target: (ParsedPath | null);
-    lineMarker: null;
+    lineMarker: (TextLineMarker | null);
     body: (MatcherBody | null);
     position: Position;
 }
 export interface FoldStatement {
     op: "FOLD";
-    suffix: string;
+    delimiter: string;
+    annotation: (string | null);
     signal: (string[] | null);
     target: (ParsedPath | null);
-    lineMarker: null;
+    lineMarker: (TextLineMarker | null);
     body: (MatcherBody | null);
     position: Position;
 }
 export interface EditStatement {
     op: "EDIT";
-    suffix: string;
+    delimiter: string;
+    annotation: (string | null);
     signal: (string[] | null);
     target: (ParsedPath | null);
     lineMarker: (TextLineMarker | null);
@@ -201,7 +383,8 @@ export interface EditStatement {
 }
 export interface CopyStatement {
     op: "COPY";
-    suffix: string;
+    delimiter: string;
+    annotation: (string | null);
     signal: (string[] | null);
     target: (ParsedPath | null);
     lineMarker: (TextLineMarker | null);
@@ -217,7 +400,8 @@ export interface ResourceSelection {
 }
 export interface MoveStatement {
     op: "MOVE";
-    suffix: string;
+    delimiter: string;
+    annotation: (string | null);
     signal: (string[] | null);
     target: (ParsedPath | null);
     lineMarker: (TextLineMarker | null);
@@ -226,7 +410,8 @@ export interface MoveStatement {
 }
 export interface SendStatement {
     op: "SEND";
-    suffix: string;
+    delimiter: string;
+    annotation: (string | null);
     signal: (number | null);
     target: (ParsedPath | null);
     lineMarker: (LineMarker | null);
@@ -242,7 +427,8 @@ export interface SendBody {
 }
 export interface ExecStatement {
     op: "EXEC";
-    suffix: string;
+    delimiter: string;
+    annotation: (string | null);
     signal: (string | null);
     target: (ParsedPath | null);
     lineMarker: (LineMarker | null);
@@ -251,7 +437,8 @@ export interface ExecStatement {
 }
 export interface BareStatement {
     op: "BARE";
-    suffix: string;
+    delimiter: string;
+    annotation: (string | null);
     signal: (string[] | null);
     target: null;
     lineMarker: null;
@@ -260,7 +447,8 @@ export interface BareStatement {
 }
 export interface WorkStatement {
     op: "WORK";
-    suffix: string;
+    delimiter: string;
+    annotation: (string | null);
     signal: (string | null);
     target: (ParsedPath | null);
     lineMarker: null;
@@ -269,7 +457,8 @@ export interface WorkStatement {
 }
 export interface ForkStatement {
     op: "FORK";
-    suffix: string;
+    delimiter: string;
+    annotation: (string | null);
     signal: (string | null);
     target: (ParsedPath | null);
     lineMarker: null;
@@ -278,7 +467,8 @@ export interface ForkStatement {
 }
 export interface KillStatement {
     op: "KILL";
-    suffix: string;
+    delimiter: string;
+    annotation: (string | null);
     signal: (number | null);
     target: (ParsedPath | null);
     lineMarker: null;
@@ -287,16 +477,41 @@ export interface KillStatement {
 }
 export interface PlanStatement {
     op: "PLAN";
-    suffix: string;
+    delimiter: string;
+    annotation: (string | null);
     signal: (string[] | null);
     target: (ParsedPath | null);
     lineMarker: (LineMarker | null);
-    body: (string | null);
+    body: Plan;
     position: Position;
 }
+/**
+ * One finding, task, or goal in the model's working-memory plan.
+ */
+export interface PlanEntry {
+    /**
+     * Human-readable description of what this task aims to accomplish.
+     */
+    content: string;
+    /**
+     * The relative importance of this task.
+     */
+    priority: ("high" | "medium" | "low");
+    /**
+     * The current execution status of this task.
+     */
+    status: ("pending" | "in_progress" | "completed" | "memory");
+    /**
+     * Opaque entry metadata preserved through standards projection.
+     */
+    _meta?: ({
+        [k: string]: unknown;
+    } | null);
+}
 export interface LookStatement {
     op: "LOOK";
-    suffix: string;
+    delimiter: string;
+    annotation: AnnotationOrNull;
     signal: TagSignal;
     target: PathOrNull;
     lineMarker: TextLineMarkerOrNull;
@@ -305,7 +520,8 @@ export interface LookStatement {
 }
 export interface BuffStatement {
     op: "BUFF";
-    suffix: string;
+    delimiter: string;
+    annotation: AnnotationOrNull;
     signal: TagSignal;
     target: PathOrNull;
     lineMarker: LineMarkerOrNull;
@@ -373,6 +589,76 @@ export interface ProblemDetails {
     retryable?: boolean;
     [k: string]: unknown;
 }
+export interface FunctionalityCandidate {
+    /**
+     * The alias the candidate would take if added; a suggestion, never authority.
+     */
+    alias?: string;
+    summary?: string;
+    /**
+     * The exact family definition, conforming to the family's definition schema.
+     */
+    definition: {};
+    provenance: {
+        kind: string;
+        source: string;
+        reference?: string;
+    };
+}
+export type FunctionalityDefinitionState = ({
+    [k: string]: unknown;
+} & {
+    alias: string;
+    origin: ("service" | "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.
+     */
+    state: ("disabled" | "active" | "unavailable" | "authorization-required");
+    definition?: {};
+    /**
+     * Family-owned presentation facts about an active definition (a server's protocol version and tool names, an agent card summary). Never credentials, never authority.
+     */
+    detail?: {};
+    problem?: ProblemDetails;
+    authorization?: {
+        url: string;
+    };
+});
+/**
+ * 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 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.
+     */
+    configuration?: {};
+}
+export interface FunctionalityDiscoverResult {
+    family: string;
+    candidates: FunctionalityCandidate[];
+}
+/**
+ * One inert discovery result: an exact family definition with its provenance. Discovery never installs, persists, enables, or executes it.
+ */
+export interface FunctionalityListResult {
+    family: string;
+    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.
+ */
+export interface FunctionalityMutationResult {
+    status: (200 | 201 | 202);
+    family: string;
+    alias: string;
+    definition?: FunctionalityDefinitionState;
+    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.
+ */
 export interface LoopFlags {
     mode: ("ask" | "act");
     auto: boolean;
@@ -380,6 +666,9 @@ export interface LoopFlags {
     noInteraction: boolean;
     noProposals: boolean;
 }
+export interface McpConfigurationOverlay {
+    [k: string]: string;
+}
 export type McpServerDefinition = ({
     [k: string]: unknown;
 } & {
@@ -418,11 +707,116 @@ export type McpServerDefinition = ({
         clientId: string;
         clientSecret: EnvironmentReference;
         scope?: string;
+        issuer?: string;
     });
     tools?: string[];
     read?: string[];
 });
 export type EnvironmentReference = string;
+export type McpServerArguments = string[];
+export type McpServerAuthorization = ({
+    type: "bearer";
+    token: string;
+} | {
+    type: "oauth";
+    redirectUrl: string;
+    clientMetadataUrl: string;
+    scope?: string;
+} | {
+    type: "oauth";
+    redirectUrl: string;
+    clientId: string;
+    clientSecret: string;
+    scope?: string;
+} | {
+    type: "oauth";
+    redirectUrl: string;
+    scope?: string;
+} | {
+    type: "client-credentials";
+    clientId: string;
+    clientSecret: string;
+    scope?: string;
+    issuer?: string;
+});
+export type McpServerToolNames = string[];
+export type McpServerReadTools = string[];
+export interface McpServerOptions {
+    args?: McpServerArguments;
+    cwd?: string;
+    env?: McpServerEnvironment;
+    headers?: McpServerHeaders;
+    authorization?: McpServerAuthorization;
+    tools?: McpServerToolNames;
+    read?: McpServerReadTools;
+}
+export interface McpServerEnvironment {
+    [k: string]: string;
+}
+export interface McpServerHeaders {
+    [k: string]: string;
+}
+export interface ModelCatalogPage {
+    /**
+     * @maxItems 100
+     */
+    items: ModelCatalogEntry[];
+    offset: number;
+    total: number;
+    nextOffset?: number;
+}
+export interface ModelCatalogEntry {
+    selector: string;
+    provider: string;
+    providerName: string;
+    model: string;
+    modelName: string;
+    limits: ModelCatalogLimits;
+    capabilities: ModelCatalogCapabilities;
+    readiness: ModelReadiness;
+}
+export interface ModelCatalogLimits {
+    contextTokens: number;
+    inputTokens?: number;
+    outputTokens?: number;
+}
+export interface ModelCatalogCapabilities {
+    attachment: boolean;
+    reasoning: boolean;
+    toolCall: boolean;
+    structuredOutput?: boolean;
+    temperature?: boolean;
+    inputModalities: string[];
+    outputModalities: string[];
+}
+/**
+ * Local configuration evidence that a catalog provider is ready to attempt a request, without probing or validating credentials.
+ */
+export interface ModelReadiness {
+    ready: boolean;
+    causes: ModelReadinessCause[];
+}
+export interface ModelReadinessCause {
+    kind: ("credential" | "configuration");
+    /**
+     * Alternative environment-variable sets. Every name in one inner array is required; satisfying any inner array resolves this cause.
+     *
+     * @minItems 1
+     */
+    alternatives: [[string, ...(string)[]], ...([string, ...(string)[]])[]];
+}
+export interface ModelCatalogQuery {
+    provider?: string;
+    search?: string;
+    availability?: ("configured" | "all");
+    offset?: number;
+    limit?: number;
+}
+export interface ModelRoute {
+    alias?: string;
+    provider: string;
+    model: string;
+}
 export interface Notice {
     /**
      * Producer identifier. Top-level for self-contained subsystems; colon-namespaced for parameterized producers such as `provider:openai` or `exec:search`.
@@ -512,6 +906,7 @@ export interface ProposalProjection {
     op: ("FIND" | "READ" | "EDIT" | "COPY" | "MOVE" | "OPEN" | "FOLD" | "SEND" | "EXEC" | "BARE" | "WORK" | "FORK" | "KILL" | "PLAN");
     target: {
         scheme: (string | null);
+        authority: (string | null);
         pathname: (string | null);
     };
     body: string;
@@ -519,7 +914,6 @@ export interface ProposalProjection {
         [k: string]: unknown;
     };
     flags: LoopFlags;
-    staleClobberRisk: boolean;
     disposition: ProposalDisposition;
 }
 /**
@@ -584,6 +978,21 @@ export type Tokens = number;
 /**
  * Known token quantities for one provider request. Omitted fields are unknown; explicit zero is observed or exactly derived.
  */
+export type ReasoningPolicy = ("off" | "adaptive" | "low" | "medium" | "high");
+export interface SkillDefinition {
+    /**
+     * The standard Agent Skills name: lowercase words joined by single hyphens, equal to the skill's directory name.
+     */
+    name: string;
+    /**
+     * The universal Agent Skills root: the project's `.agents/skills` or the user's `~/.agents/skills`.
+     */
+    scope: ("project" | "global");
+    /**
+     * 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.
+     */
+    source?: string;
+}
 export interface TextRegion {
     startLine: number;
     startColumn: number;