vigiles API reference
    Preparing search index...

    Variable experimental_agentConst Experimental

    experimental_agent: <
        const P extends AuthoredPurity
        | undefined = undefined,
        V extends ToolVocabulary = OpenToolVocabulary,
        Ok extends
            Readonly<Record<string, OutputFieldType>> = Readonly<
            Record<string, OutputFieldType>,
        >,
        Err extends
            Readonly<Record<string, OutputFieldType>> = Readonly<
            Record<string, OutputFieldType>,
        >,
    >(
        spec: AgentSpecInput<P, V, Ok, Err>,
    ) => TypedAgentSpec<Ok, Err> & {
        andThen: <
            PriorOk extends Readonly<Record<string, OutputFieldType>>,
            PriorErr extends Readonly<Record<string, OutputFieldType>>,
            Needs extends Readonly<Record<string, OutputFieldType>>,
            Ok extends Readonly<Record<string, OutputFieldType>>,
            Err extends Readonly<Record<string, OutputFieldType>>,
        >(
            prior: Pipeline<PriorOk, PriorErr>,
            next: Supplies<PriorOk, Needs> extends true
                ? PipeStep<Needs, Ok, Err>
                : { __HANDOFF_ERROR: Supplies<PriorOk, Needs> },
        ) => Pipeline<Ok, PriorErr | Err>;
        delegate: (
            agent: string,
            task?: string,
            needsContract?: Readonly<Record<string, OutputFieldType>>,
        ) => RailwayStep;
        needs: <const N extends Readonly<Record<string, OutputFieldType>>>(
            shape: N,
        ) => N;
        pipe: {
            <
                A extends Readonly<Record<string, OutputFieldType>>,
                AE extends Readonly<Record<string, OutputFieldType>>,
            >(
                a: TypedAgentSpec<A, AE>,
            ): Pipeline<A, AE>;
            <
                A extends Readonly<Record<string, OutputFieldType>>,
                AE extends Readonly<Record<string, OutputFieldType>>,
                BN extends Readonly<Record<string, OutputFieldType>>,
                B extends Readonly<Record<string, OutputFieldType>>,
                BE extends Readonly<Record<string, OutputFieldType>>,
            >(
                a: TypedAgentSpec<A, AE>,
                b: Supplies<A, BN> extends true
                    ? PipeStep<BN, B, BE>
                    : { __HANDOFF_ERROR: Supplies<A, BN> },
            ): Pipeline<B, AE | BE>;
            <
                A extends Readonly<Record<string, OutputFieldType>>,
                AE extends Readonly<Record<string, OutputFieldType>>,
                BN extends Readonly<Record<string, OutputFieldType>>,
                B extends Readonly<Record<string, OutputFieldType>>,
                BE extends Readonly<Record<string, OutputFieldType>>,
                CN extends Readonly<Record<string, OutputFieldType>>,
                C extends Readonly<Record<string, OutputFieldType>>,
                CE extends Readonly<Record<string, OutputFieldType>>,
            >(
                a: TypedAgentSpec<A, AE>,
                b: Supplies<A, BN> extends true
                    ? PipeStep<BN, B, BE>
                    : { __HANDOFF_ERROR: Supplies<A, BN> },
                c: Supplies<B, CN> extends true
                    ? PipeStep<CN, C, CE>
                    : { __HANDOFF_ERROR: Supplies<B, CN> },
            ): Pipeline<C, AE | BE | CE>;
            <
                A extends Readonly<Record<string, OutputFieldType>>,
                AE extends Readonly<Record<string, OutputFieldType>>,
                BN extends Readonly<Record<string, OutputFieldType>>,
                B extends Readonly<Record<string, OutputFieldType>>,
                BE extends Readonly<Record<string, OutputFieldType>>,
                CN extends Readonly<Record<string, OutputFieldType>>,
                C extends Readonly<Record<string, OutputFieldType>>,
                CE extends Readonly<Record<string, OutputFieldType>>,
                DN extends Readonly<Record<string, OutputFieldType>>,
                D extends Readonly<Record<string, OutputFieldType>>,
                DE extends Readonly<Record<string, OutputFieldType>>,
            >(
                a: TypedAgentSpec<A, AE>,
                b: Supplies<A, BN> extends true
                    ? PipeStep<BN, B, BE>
                    : { __HANDOFF_ERROR: Supplies<A, BN> },
                c: Supplies<B, CN> extends true
                    ? PipeStep<CN, C, CE>
                    : { __HANDOFF_ERROR: Supplies<B, CN> },
                d: Supplies<C, DN> extends true
                    ? PipeStep<DN, D, DE>
                    : { __HANDOFF_ERROR: Supplies<C, DN> },
            ): Pipeline<D, AE | BE | CE | DE>;
        };
        pipeStep: <
            Needs extends Readonly<Record<string, OutputFieldType>>,
            Ok extends Readonly<Record<string, OutputFieldType>>,
            Err extends Readonly<Record<string, OutputFieldType>>,
        >(
            a: TypedAgentSpec<Ok, Err>,
            needsContract?: Needs,
        ) => PipeStep<Needs, Ok, Err>;
        railway: (spec: Omit<Railway, "_specType">) => Railway;
        result: <
            const Ok extends Readonly<Record<string, OutputFieldType>>,
            const Err extends Readonly<Record<string, OutputFieldType>>,
        >(
            ok: Ok,
            err: Err,
        ) => OutputContract<Ok, Err>;
        start: <
            Ok extends Readonly<Record<string, OutputFieldType>>,
            Err extends Readonly<Record<string, OutputFieldType>>,
        >(
            first:
                | PipeStep<Record<string, never>, Ok, Err>
                | TypedAgentSpec<Ok, Err>,
        ) => Pipeline<Ok, Err>;
    } = ...

    Define a subagent — and the ROOT of the subagent vocabulary.

    Everything that only makes sense for subagents hangs off this one symbol: experimental_agent.result() (the outcome contract), .railway() / .delegate() (the flat orchestrator), and .pipe() / .start() / .andThen() / .pipeStep() / .needs() (the typed pipeline). Same chokepoint as experimental_skill.input().

    WHY a root and not a prefix on each name: railway() and delegate() are meaningless without a subagent, yet they shipped under STABLE names while the builder they depend on is experimental — a stable name resting on an unstable one. Prefixing each would carry the warning but multiply the vocabulary; a namespace OBJECT was rejected for the reason the vigiles/experimental subpath was retired in #169 — it marks the import line, out of view by the time anyone reads the call. A member reached through the marked root cannot be destructured free of its warning without renaming it, so the warning rides every call site.

    The rule this establishes: ONE experimental root per feature, everything else a member of it, TYPES excluded (a type annotation is not a call site).

    Type Declaration

      • <
            const P extends AuthoredPurity
            | undefined = undefined,
            V extends ToolVocabulary = OpenToolVocabulary,
            Ok extends
                Readonly<Record<string, OutputFieldType>> = Readonly<
                Record<string, OutputFieldType>,
            >,
            Err extends
                Readonly<Record<string, OutputFieldType>> = Readonly<
                Record<string, OutputFieldType>,
            >,
        >(
            spec: AgentSpecInput<P, V, Ok, Err>,
        ): TypedAgentSpec<Ok, Err>
      • Experimental

        Define a subagent specification (compiles to agents/<name>.md).

        // agents/reviewer.md.spec.ts export default experimental_agent({ name: "reviewer", description: "Review a diff for correctness. Dispatch PROACTIVELY after edits.", model: "sonnet", tools: ["Read", "Grep", "Bash"], body: proseReview the diff. Run ${cmd("npm test")} first., rules: { "no-floating": enforce("@typescript-eslint/no-floating-promises", "Await promises."), }, });

        Generic over a tool Vocabulary (default OpenToolVocabulary — no constraint). A harness adapter re-exports a vocabulary-bound agent (e.g. vigiles/claude-code) so purity: "pure" + a side-effecting tool is a tsc error at edit time; the bare core experimental_agent() accepts any tools, as before.

        Also generic over the result's Ok/Err shapes, inferred from output: result(...). The returned value is a TypedAgentSpec<Ok, Err> — an AgentSpec that carries those shapes at the type level, so a typed pipe can cross-reference the handoff. With no output the shapes default to the erased Shape, and the value is still a plain AgentSpec — backwards-compatible.

        The SHAPE is not settled — the author is unsure of the design, which is exactly what this marker promises: the form may change. It is NOT a claim that the surface is unproven. Measured 2026-06-20: real Claude Code loaded a compiled agents/code-reviewer.md, dispatched to it and read it, 100% of trials — stronger end-to-end evidence than experimental_skill has.

        Type Parameters

        Parameters

        Returns TypedAgentSpec<Ok, Err>

    • andThen: <
          PriorOk extends Readonly<Record<string, OutputFieldType>>,
          PriorErr extends Readonly<Record<string, OutputFieldType>>,
          Needs extends Readonly<Record<string, OutputFieldType>>,
          Ok extends Readonly<Record<string, OutputFieldType>>,
          Err extends Readonly<Record<string, OutputFieldType>>,
      >(
          prior: Pipeline<PriorOk, PriorErr>,
          next: Supplies<PriorOk, Needs> extends true
              ? PipeStep<Needs, Ok, Err>
              : { __HANDOFF_ERROR: Supplies<PriorOk, Needs> },
      ) => Pipeline<Ok, PriorErr | Err>
    • delegate: (
          agent: string,
          task?: string,
          needsContract?: Readonly<Record<string, OutputFieldType>>,
      ) => RailwayStep
    • needs: <const N extends Readonly<Record<string, OutputFieldType>>>(shape: N) => N
    • pipe: {
          <
              A extends Readonly<Record<string, OutputFieldType>>,
              AE extends Readonly<Record<string, OutputFieldType>>,
          >(
              a: TypedAgentSpec<A, AE>,
          ): Pipeline<A, AE>;
          <
              A extends Readonly<Record<string, OutputFieldType>>,
              AE extends Readonly<Record<string, OutputFieldType>>,
              BN extends Readonly<Record<string, OutputFieldType>>,
              B extends Readonly<Record<string, OutputFieldType>>,
              BE extends Readonly<Record<string, OutputFieldType>>,
          >(
              a: TypedAgentSpec<A, AE>,
              b: Supplies<A, BN> extends true
                  ? PipeStep<BN, B, BE>
                  : { __HANDOFF_ERROR: Supplies<A, BN> },
          ): Pipeline<B, AE | BE>;
          <
              A extends Readonly<Record<string, OutputFieldType>>,
              AE extends Readonly<Record<string, OutputFieldType>>,
              BN extends Readonly<Record<string, OutputFieldType>>,
              B extends Readonly<Record<string, OutputFieldType>>,
              BE extends Readonly<Record<string, OutputFieldType>>,
              CN extends Readonly<Record<string, OutputFieldType>>,
              C extends Readonly<Record<string, OutputFieldType>>,
              CE extends Readonly<Record<string, OutputFieldType>>,
          >(
              a: TypedAgentSpec<A, AE>,
              b: Supplies<A, BN> extends true
                  ? PipeStep<BN, B, BE>
                  : { __HANDOFF_ERROR: Supplies<A, BN> },
              c: Supplies<B, CN> extends true
                  ? PipeStep<CN, C, CE>
                  : { __HANDOFF_ERROR: Supplies<B, CN> },
          ): Pipeline<C, AE | BE | CE>;
          <
              A extends Readonly<Record<string, OutputFieldType>>,
              AE extends Readonly<Record<string, OutputFieldType>>,
              BN extends Readonly<Record<string, OutputFieldType>>,
              B extends Readonly<Record<string, OutputFieldType>>,
              BE extends Readonly<Record<string, OutputFieldType>>,
              CN extends Readonly<Record<string, OutputFieldType>>,
              C extends Readonly<Record<string, OutputFieldType>>,
              CE extends Readonly<Record<string, OutputFieldType>>,
              DN extends Readonly<Record<string, OutputFieldType>>,
              D extends Readonly<Record<string, OutputFieldType>>,
              DE extends Readonly<Record<string, OutputFieldType>>,
          >(
              a: TypedAgentSpec<A, AE>,
              b: Supplies<A, BN> extends true
                  ? PipeStep<BN, B, BE>
                  : { __HANDOFF_ERROR: Supplies<A, BN> },
              c: Supplies<B, CN> extends true
                  ? PipeStep<CN, C, CE>
                  : { __HANDOFF_ERROR: Supplies<B, CN> },
              d: Supplies<C, DN> extends true
                  ? PipeStep<DN, D, DE>
                  : { __HANDOFF_ERROR: Supplies<C, DN> },
          ): Pipeline<D, AE | BE | CE | DE>;
      }
    • pipeStep: <
          Needs extends Readonly<Record<string, OutputFieldType>>,
          Ok extends Readonly<Record<string, OutputFieldType>>,
          Err extends Readonly<Record<string, OutputFieldType>>,
      >(
          a: TypedAgentSpec<Ok, Err>,
          needsContract?: Needs,
      ) => PipeStep<Needs, Ok, Err>
    • railway: (spec: Omit<Railway, "_specType">) => Railway
    • result: <
          const Ok extends Readonly<Record<string, OutputFieldType>>,
          const Err extends Readonly<Record<string, OutputFieldType>>,
      >(
          ok: Ok,
          err: Err,
      ) => OutputContract<Ok, Err>
    • start: <
          Ok extends Readonly<Record<string, OutputFieldType>>,
          Err extends Readonly<Record<string, OutputFieldType>>,
      >(
          first:
              | PipeStep<Record<string, never>, Ok, Err>
              | TypedAgentSpec<Ok, Err>,
      ) => Pipeline<Ok, Err>

    Settings

    Member Visibility