@ghx-dev/core 0.2.0 → 0.2.2

package/dist/index.d.ts

@@ -1,5 +1,10 @@
 import { DocumentNode } from 'graphql';
 
+/**
+ * All possible error codes returned in {@link ResultError.code}.
+ *
+ * Retryable codes: `RATE_LIMIT`, `NETWORK`, `SERVER`.
+ */
 declare const errorCodes: {
     readonly Auth: "AUTH";
     readonly NotFound: "NOT_FOUND";
@@ -10,24 +15,49 @@ declare const errorCodes: {
     readonly AdapterUnsupported: "ADAPTER_UNSUPPORTED";
     readonly Unknown: "UNKNOWN";
 };
+/** Union of all error code string literals. */
 type ErrorCode = (typeof errorCodes)[keyof typeof errorCodes];
 
+/**
+ * All possible reason codes explaining why a particular route was selected.
+ *
+ * Included in {@link ResultMeta.reason}.
+ */
 declare const routeReasonCodes: readonly ["INPUT_VALIDATION", "OUTPUT_VALIDATION", "CARD_PREFERRED", "CARD_FALLBACK", "PREFLIGHT_FAILED", "ENV_CONSTRAINT", "CAPABILITY_LIMIT", "DEFAULT_POLICY"];
+/** Reason code explaining why a particular route was selected. */
 type RouteReasonCode = (typeof routeReasonCodes)[number];
 
+/** The transport route used to execute a capability. */
 type RouteSource = "cli" | "rest" | "graphql";
+/**
+ * Structured error returned inside a {@link ResultEnvelope} when `ok` is `false`.
+ *
+ * @see {@link ErrorCode} for the full list of error codes.
+ */
 interface ResultError {
     code: ErrorCode;
     message: string;
     retryable: boolean;
     details?: Record<string, unknown>;
 }
+/**
+ * Records a single route attempt during execution.
+ *
+ * The routing engine may try multiple routes (preferred → fallback).
+ * Each attempt is logged here regardless of outcome.
+ */
 interface AttemptMeta {
     route: RouteSource;
     status: "success" | "error" | "skipped";
     error_code?: ErrorCode;
     duration_ms?: number;
 }
+/**
+ * Metadata attached to every {@link ResultEnvelope}.
+ *
+ * Provides observability into which route was used, why, how long it took,
+ * and the full list of route attempts.
+ */
 interface ResultMeta {
     capability_id: string;
     route_used?: RouteSource;
@@ -47,19 +77,35 @@ interface ResultMeta {
         tokens_out?: number;
     };
 }
+/**
+ * The universal response contract for all ghx operations.
+ *
+ * Every call to {@link executeTask} returns a `ResultEnvelope` — it never throws.
+ * Check `ok` to distinguish success from failure; `data` and `error` are exclusive.
+ *
+ * @typeParam TData - The shape of the success payload, varies per capability.
+ */
 interface ResultEnvelope<TData = unknown> {
     ok: boolean;
     data?: TData;
     error?: ResultError;
     meta: ResultMeta;
 }
+/** Aggregate outcome of a batch execution via {@link executeTasks}. */
 type ChainStatus = "success" | "partial" | "failed";
+/** Result of a single step within a chain execution. */
 interface ChainStepResult {
     task: string;
     ok: boolean;
     data?: unknown;
     error?: ResultError;
 }
+/**
+ * Response envelope for batch operations via {@link executeTasks}.
+ *
+ * Contains per-step results and aggregate metadata
+ * (total, succeeded, failed counts).
+ */
 interface ChainResultEnvelope {
     status: ChainStatus;
     results: ChainStepResult[];
@@ -71,7 +117,13 @@ interface ChainResultEnvelope {
     };
 }
 
+/** A dotted capability identifier (e.g. `"pr.view"`, `"issue.labels.add"`). */
 type TaskId = string;
+/**
+ * A request to execute a single ghx capability.
+ *
+ * @typeParam TInput - The shape of the input payload, varies per capability.
+ */
 interface TaskRequest<TInput = Record<string, unknown>> {
     task: TaskId;
     input: TInput;
@@ -82,13 +134,28 @@ type ExecuteTaskFn = (request: {
     input: Record<string, unknown>;
     options?: Record<string, unknown>;
 }) => Promise<ResultEnvelope>;
+/**
+ * Creates an execute tool suitable for wiring into an AI agent's tool loop.
+ *
+ * Wraps the execution engine into a simple `{ execute(capabilityId, params) }` shape.
+ *
+ * @example
+ * ```ts
+ * const tool = createExecuteTool({
+ *   executeTask: (req) => executeTask(req, deps),
+ * })
+ * const result = await tool.execute("repo.view", { owner: "aryeko", name: "ghx" })
+ * ```
+ */
 declare function createExecuteTool(deps: {
     executeTask: ExecuteTaskFn;
 }): {
     execute(capabilityId: string, params: Record<string, unknown>, options?: Record<string, unknown>): Promise<ResultEnvelope>;
 };
 
+/** Represents a JSON Schema definition for card inputs/outputs. */
 type JsonSchema = Record<string, unknown>;
+/** Defines when a fallback route should override the preferred route. */
 interface SuitabilityRule {
     when: "always" | "env" | "params";
     predicate: string;
@@ -173,16 +240,25 @@ interface NullLiteralInject {
     target: string;
     source: "null_literal";
 }
+/** A specification for how to inject a resolved Phase 1 value into Phase 2. */
 type InjectSpec = ScalarInject | MapArrayInject | InputPassthroughInject | NullLiteralInject;
+/** Defines the GraphQL query to run during the Phase 1 lookup. */
 interface LookupSpec {
     operationName: string;
     documentPath: string;
     vars: Record<string, string>;
 }
+/** Configuration for a Phase 1 node ID lookup prior to mutation execution. */
 interface ResolutionConfig {
     lookup: LookupSpec;
     inject: InjectSpec[];
 }
+/**
+ * Declarative configuration for a single ghx capability.
+ *
+ * Defines the capability's identity, input/output schemas, routing preferences,
+ * and adapter-specific execution details (GraphQL, CLI, REST).
+ */
 interface OperationCard<Input = Record<string, unknown>> {
     capability_id: string;
     version: string;
@@ -197,6 +273,7 @@ interface OperationCard<Input = Record<string, unknown>> {
     };
     graphql?: {
         operationName: string;
+        operationType: "query" | "mutation";
         documentPath: string;
         variables?: Record<string, string>;
         limits?: {
@@ -238,6 +315,7 @@ type SafeRunnerOptions = {
 };
 declare function createSafeCliCommandRunner(options?: SafeRunnerOptions): CliCommandRunner;
 
+/** Structured explanation of a capability, returned by {@link explainCapability}. */
 type CapabilityExplanation = {
     capability_id: string;
     purpose: string;
@@ -247,11 +325,19 @@ type CapabilityExplanation = {
     fallback_routes: Array<"cli" | "graphql" | "rest">;
     output_fields: string[];
 };
+/**
+ * Return a structured explanation of a capability by its ID.
+ *
+ * @throws If the capability ID is unknown.
+ */
 declare function explainCapability(capabilityId: string): CapabilityExplanation;
 
+/** Return a copy of all registered operation cards, in canonical order. */
 declare function listOperationCards(): OperationCard[];
+/** Look up a single operation card by its dotted capability ID (e.g. `"pr.view"`). */
 declare function getOperationCard(capabilityId: string): OperationCard | undefined;
 
+/** Summary of a capability, returned by {@link listCapabilities}. */
 type CapabilityListItem = {
     capability_id: string;
     description: string;
@@ -259,31 +345,56 @@ type CapabilityListItem = {
     optional_inputs: string[];
     optional_inputs_detail: Record<string, unknown>;
 };
+/**
+ * List all available capabilities, optionally filtered by domain.
+ *
+ * @param domain - Filter by top-level domain (e.g. `"pr"`, `"issue"`, `"workflow"`).
+ */
 declare function listCapabilities(domain?: string): CapabilityListItem[];
 
 type GraphqlVariables = Record<string, unknown>;
+/** A single error from a GraphQL response. */
 type GraphqlError = {
     message: string;
     path?: ReadonlyArray<string | number>;
     extensions?: Record<string, unknown>;
 };
+/** Raw GraphQL response containing both `data` and `errors` fields. */
 type GraphqlRawResult<TData> = {
     data: TData | undefined;
     errors: GraphqlError[] | undefined;
 };
 type GraphqlDocument = string | DocumentNode;
+/**
+ * Low-level transport interface for sending GraphQL queries.
+ *
+ * Implement this to use a custom HTTP client, proxy, or mock.
+ * Pass to {@link createGithubClient} or {@link createGraphqlClient}.
+ */
 interface GraphqlTransport {
     execute<TData>(query: string, variables?: GraphqlVariables): Promise<TData>;
     executeRaw?<TData>(query: string, variables?: GraphqlVariables): Promise<GraphqlRawResult<TData>>;
 }
+/**
+ * Higher-level GraphQL client with `query` and `queryRaw` methods.
+ *
+ * Created by {@link createGraphqlClient} from a {@link GraphqlTransport}.
+ */
 interface GraphqlClient {
     query<TData, TVariables extends GraphqlVariables = GraphqlVariables>(query: GraphqlDocument, variables?: TVariables): Promise<TData>;
     queryRaw<TData, TVariables extends GraphqlVariables = GraphqlVariables>(query: GraphqlDocument, variables?: TVariables): Promise<GraphqlRawResult<TData>>;
 }
+/** Options for creating a token-based GraphQL transport. */
 type TokenClientOptions = {
     token: string;
     graphqlUrl?: string;
 };
+/**
+ * Create a {@link GraphqlClient} from a {@link GraphqlTransport}.
+ *
+ * Wraps the raw transport `execute` method with query string normalization
+ * and a `queryRaw` method that returns settled results.
+ */
 declare function createGraphqlClient(transport: GraphqlTransport): GraphqlClient;
 
 type Maybe<T> = T | null;
@@ -383,6 +494,57 @@ type PrViewQueryVariables = Exact<{
     prNumber: Scalars["Int"]["input"];
 }>;
 
+type ProjectV2FieldsListQueryVariables = Exact<{
+    owner: Scalars["String"]["input"];
+    projectNumber: Scalars["Int"]["input"];
+    first: Scalars["Int"]["input"];
+    after?: InputMaybe<Scalars["String"]["input"]>;
+}>;
+
+type ProjectV2ItemsListQueryVariables = Exact<{
+    owner: Scalars["String"]["input"];
+    projectNumber: Scalars["Int"]["input"];
+    first: Scalars["Int"]["input"];
+    after?: InputMaybe<Scalars["String"]["input"]>;
+}>;
+
+type ProjectV2OrgViewQueryVariables = Exact<{
+    org: Scalars["String"]["input"];
+    projectNumber: Scalars["Int"]["input"];
+}>;
+
+type ProjectV2UserViewQueryVariables = Exact<{
+    user: Scalars["String"]["input"];
+    projectNumber: Scalars["Int"]["input"];
+}>;
+
+type ReleaseListQueryVariables = Exact<{
+    owner: Scalars["String"]["input"];
+    name: Scalars["String"]["input"];
+    first: Scalars["Int"]["input"];
+    after?: InputMaybe<Scalars["String"]["input"]>;
+}>;
+
+type ReleaseViewQueryVariables = Exact<{
+    owner: Scalars["String"]["input"];
+    name: Scalars["String"]["input"];
+    tagName: Scalars["String"]["input"];
+}>;
+
+type RepoIssueTypesListQueryVariables = Exact<{
+    owner: Scalars["String"]["input"];
+    name: Scalars["String"]["input"];
+    first: Scalars["Int"]["input"];
+    after?: InputMaybe<Scalars["String"]["input"]>;
+}>;
+
+type RepoLabelsListQueryVariables = Exact<{
+    owner: Scalars["String"]["input"];
+    name: Scalars["String"]["input"];
+    first: Scalars["Int"]["input"];
+    after?: InputMaybe<Scalars["String"]["input"]>;
+}>;
+
 type RepoViewQueryVariables = Exact<{
     owner: Scalars["String"]["input"];
     name: Scalars["String"]["input"];
@@ -547,6 +709,16 @@ type IssueLabelsAddData = {
     id: string;
     labels: string[];
 };
+type IssueLabelsRemoveInput = {
+    owner: string;
+    name: string;
+    issueNumber: number;
+    labels: string[];
+};
+type IssueLabelsRemoveData = {
+    issueNumber: number;
+    removed: string[];
+};
 type IssueAssigneesUpdateData = {
     id: string;
     assignees: string[];
@@ -563,6 +735,15 @@ type IssueMilestoneSetData = {
     id: string;
     milestoneNumber: number | null;
 };
+type IssueMilestoneClearInput = {
+    owner: string;
+    name: string;
+    issueNumber: number;
+};
+type IssueMilestoneClearData = {
+    issueNumber: number;
+    cleared: boolean;
+};
 type IssueCommentCreateData = {
     id: string;
     body: string;
@@ -736,7 +917,220 @@ type PrReviewSubmitData = {
     url: string;
     body: string | null;
 };
+type RepoLabelsListInput = RepoLabelsListQueryVariables;
+type RepoLabelItemData = {
+    id: string | null;
+    name: string | null;
+    description: string | null;
+    color: string | null;
+    isDefault: boolean | null;
+};
+type RepoLabelsListData = {
+    items: RepoLabelItemData[];
+    pageInfo: {
+        hasNextPage: boolean;
+        endCursor: string | null;
+    };
+};
+type RepoIssueTypesListInput = RepoIssueTypesListQueryVariables;
+type RepoIssueTypeItemData = {
+    id: string | null;
+    name: string | null;
+    color: string | null;
+    isEnabled: boolean | null;
+};
+type RepoIssueTypesListData = {
+    items: RepoIssueTypeItemData[];
+    pageInfo: {
+        hasNextPage: boolean;
+        endCursor: string | null;
+    };
+};
+type ReleaseViewInput = ReleaseViewQueryVariables;
+type ReleaseViewData = {
+    id: number | null;
+    tagName: string;
+    name: string | null;
+    isDraft: boolean;
+    isPrerelease: boolean;
+    url: string | null;
+    targetCommitish: string | null;
+    createdAt: string | null;
+    publishedAt: string | null;
+};
+type ReleaseListInput = ReleaseListQueryVariables;
+type ReleaseItemData = ReleaseViewData;
+type ReleaseListData = {
+    items: ReleaseItemData[];
+    pageInfo: {
+        hasNextPage: boolean;
+        endCursor: string | null;
+    };
+};
+type ProjectV2OrgViewInput = ProjectV2OrgViewQueryVariables;
+type ProjectV2OrgViewData = {
+    id: string | null;
+    title: string | null;
+    shortDescription: string | null;
+    public: boolean | null;
+    closed: boolean | null;
+    url: string | null;
+};
+type ProjectV2UserViewInput = ProjectV2UserViewQueryVariables;
+type ProjectV2UserViewData = ProjectV2OrgViewData;
+type ProjectV2FieldsListInput = ProjectV2FieldsListQueryVariables;
+type ProjectV2FieldItemData = {
+    id: string | null;
+    name: string | null;
+    dataType: string | null;
+    options?: Array<{
+        id: string;
+        name: string;
+    }> | null;
+};
+type ProjectV2FieldsListData = {
+    items: ProjectV2FieldItemData[];
+    pageInfo: {
+        hasNextPage: boolean;
+        endCursor: string | null;
+    };
+};
+type ProjectV2ItemsListInput = ProjectV2ItemsListQueryVariables;
+type ProjectV2ItemData = {
+    id: string | null;
+    contentType: string | null;
+    contentNumber: number | null;
+    contentTitle: string | null;
+};
+type ProjectV2ItemsListData = {
+    items: ProjectV2ItemData[];
+    pageInfo: {
+        hasNextPage: boolean;
+        endCursor: string | null;
+    };
+};
+type PrCreateInput = {
+    owner: string;
+    name: string;
+    baseRefName: string;
+    headRefName: string;
+    title: string;
+    body?: string;
+    draft?: boolean;
+};
+type PrCreateData = {
+    number: number;
+    url: string;
+    title: string;
+    state: string;
+    draft: boolean;
+};
+type PrUpdateInput = {
+    owner: string;
+    name: string;
+    prNumber: number;
+    title?: string;
+    body?: string;
+    draft?: boolean;
+};
+type PrUpdateData = {
+    number: number;
+    url: string;
+    title: string;
+    state: string;
+    draft: boolean;
+};
+type PrMergeInput = {
+    owner: string;
+    name: string;
+    prNumber: number;
+    mergeMethod?: string;
+    deleteBranch?: boolean;
+};
+type PrMergeData = {
+    prNumber: number;
+    method: string;
+    isMethodAssumed: boolean;
+    queued: boolean;
+    deleteBranch: boolean;
+};
+type PrBranchUpdateInput = {
+    owner: string;
+    name: string;
+    prNumber: number;
+    updateMethod?: string;
+};
+type PrBranchUpdateData = {
+    prNumber: number;
+    updated: boolean;
+};
+type PrAssigneesInput = {
+    owner: string;
+    name: string;
+    prNumber: number;
+    assignees: string[];
+};
+type PrAssigneesAddInput = PrAssigneesInput;
+type PrAssigneesRemoveInput = PrAssigneesInput;
+type PrAssigneesAddData = {
+    prNumber: number;
+    added: string[];
+};
+type PrAssigneesRemoveData = {
+    prNumber: number;
+    removed: string[];
+};
+type PrReviewsRequestInput = {
+    owner: string;
+    name: string;
+    prNumber: number;
+    reviewers: string[];
+};
+type PrReviewsRequestData = {
+    prNumber: number;
+    reviewers: string[];
+    updated: boolean;
+};
+type ProjectV2ItemAddInput = {
+    owner: string;
+    projectNumber: number;
+    issueUrl: string;
+};
+type ProjectV2ItemAddData = {
+    itemId: string;
+    itemType: string | null;
+};
+type ProjectV2ItemRemoveInput = {
+    owner: string;
+    projectNumber: number;
+    itemId: string;
+};
+type ProjectV2ItemRemoveData = {
+    deletedItemId: string;
+};
+type ProjectV2ItemFieldUpdateInput = {
+    projectId: string;
+    itemId: string;
+    fieldId: string;
+    valueText?: string;
+    valueNumber?: number;
+    valueDate?: string;
+    valueSingleSelectOptionId?: string;
+    valueIterationId?: string;
+    clear?: boolean;
+};
+type ProjectV2ItemFieldUpdateData = {
+    itemId: string;
+};
 
+/**
+ * High-level GitHub API client with 50+ typed methods.
+ *
+ * Extends {@link GraphqlClient} with domain-specific helpers for issues, PRs,
+ * releases, projects, and repos. Domain modules are lazy-loaded on first use.
+ *
+ * Create via {@link createGithubClientFromToken} or {@link createGithubClient}.
+ */
 interface GithubClient extends GraphqlClient {
     fetchRepoView(input: RepoViewInput): Promise<RepoViewData>;
     fetchIssueCommentsList(input: IssueCommentsListInput): Promise<IssueCommentsListData>;
@@ -747,10 +1141,12 @@ interface GithubClient extends GraphqlClient {
     deleteIssue(input: IssueMutationInput): Promise<IssueMutationData>;
     updateIssueLabels(input: IssueLabelsUpdateInput): Promise<IssueLabelsUpdateData>;
     addIssueLabels(input: IssueLabelsAddInput): Promise<IssueLabelsAddData>;
+    removeIssueLabels(input: IssueLabelsRemoveInput): Promise<IssueLabelsRemoveData>;
     updateIssueAssignees(input: IssueAssigneesUpdateInput): Promise<IssueAssigneesUpdateData>;
     addIssueAssignees(input: IssueAssigneesAddInput): Promise<IssueAssigneesAddData>;
     removeIssueAssignees(input: IssueAssigneesRemoveInput): Promise<IssueAssigneesRemoveData>;
     setIssueMilestone(input: IssueMilestoneSetInput): Promise<IssueMilestoneSetData>;
+    clearIssueMilestone(input: IssueMilestoneClearInput): Promise<IssueMilestoneClearData>;
     createIssueComment(input: IssueCommentCreateInput): Promise<IssueCommentCreateData>;
     fetchIssueLinkedPrs(input: IssueLinkedPrsListInput): Promise<IssueLinkedPrsListData>;
     fetchIssueRelations(input: IssueRelationsGetInput): Promise<IssueRelationsGetData>;
@@ -770,10 +1166,47 @@ interface GithubClient extends GraphqlClient {
     resolveReviewThread(input: ReviewThreadMutationInput): Promise<ReviewThreadMutationData>;
     unresolveReviewThread(input: ReviewThreadMutationInput): Promise<ReviewThreadMutationData>;
     submitPrReview(input: PrReviewSubmitInput): Promise<PrReviewSubmitData>;
+    fetchRepoLabelsList(input: RepoLabelsListInput): Promise<RepoLabelsListData>;
+    fetchRepoIssueTypesList(input: RepoIssueTypesListInput): Promise<RepoIssueTypesListData>;
+    fetchReleaseView(input: ReleaseViewInput): Promise<ReleaseViewData>;
+    fetchReleaseList(input: ReleaseListInput): Promise<ReleaseListData>;
+    fetchProjectV2OrgView(input: ProjectV2OrgViewInput): Promise<ProjectV2OrgViewData>;
+    fetchProjectV2UserView(input: ProjectV2UserViewInput): Promise<ProjectV2UserViewData>;
+    fetchProjectV2FieldsList(input: ProjectV2FieldsListInput): Promise<ProjectV2FieldsListData>;
+    fetchProjectV2ItemsList(input: ProjectV2ItemsListInput): Promise<ProjectV2ItemsListData>;
+    createPr(input: PrCreateInput): Promise<PrCreateData>;
+    updatePr(input: PrUpdateInput): Promise<PrUpdateData>;
+    mergePr(input: PrMergeInput): Promise<PrMergeData>;
+    updatePrBranch(input: PrBranchUpdateInput): Promise<PrBranchUpdateData>;
+    addPrAssignees(input: PrAssigneesAddInput): Promise<PrAssigneesAddData>;
+    removePrAssignees(input: PrAssigneesRemoveInput): Promise<PrAssigneesRemoveData>;
+    requestPrReviews(input: PrReviewsRequestInput): Promise<PrReviewsRequestData>;
+    addProjectV2Item(input: ProjectV2ItemAddInput): Promise<ProjectV2ItemAddData>;
+    removeProjectV2Item(input: ProjectV2ItemRemoveInput): Promise<ProjectV2ItemRemoveData>;
+    updateProjectV2ItemField(input: ProjectV2ItemFieldUpdateInput): Promise<ProjectV2ItemFieldUpdateData>;
 }
+/**
+ * Create a {@link GithubClient} from a token (string or options object).
+ *
+ * Uses the default `fetch`-based transport. For custom transports, use
+ * {@link createGithubClient} instead.
+ *
+ * @throws If the token is empty.
+ */
 declare function createGithubClientFromToken(tokenOrOptions: string | TokenClientOptions): GithubClient;
+/**
+ * Create a {@link GithubClient} from a custom {@link GraphqlTransport}.
+ *
+ * Use this for enterprise endpoints, proxies, or test mocking.
+ */
 declare function createGithubClient(transport: GraphqlTransport): GithubClient;
 
+/**
+ * Cache for Phase 1 resolution lookups in batch execution.
+ *
+ * Avoids redundant GraphQL lookups when the same entity is referenced
+ * by multiple steps in a chain.
+ */
 interface ResolutionCache {
     get(key: string): unknown | undefined;
     set(key: string, value: unknown): void;
@@ -787,9 +1220,20 @@ interface ResolutionCacheOptions {
     /** Maximum number of cached entries. Default: 200. */
     maxEntries?: number;
 }
+/**
+ * Create an in-memory resolution cache with TTL and FIFO eviction.
+ *
+ * Pass to `ExecutionDeps.resolutionCache` for batch operations.
+ */
 declare function createResolutionCache(opts?: ResolutionCacheOptions): ResolutionCache;
+/** Build a deterministic cache key from an operation name and variables. */
 declare function buildCacheKey(operationName: string, variables: Record<string, unknown>): string;
 
+/**
+ * Dependencies required by the execution engine.
+ *
+ * Pass to {@link executeTask} or {@link executeTasks}.
+ */
 type ExecutionDeps = {
     githubClient: GithubClient;
     githubToken?: string | null;
@@ -800,7 +1244,20 @@ type ExecutionDeps = {
     reason?: RouteReasonCode;
     resolutionCache?: ResolutionCache;
 };
+
+/**
+ * Execute a single GitHub operation.
+ *
+ * Looks up the operation card, validates input, selects a route, and returns
+ * a {@link ResultEnvelope}. Never throws.
+ */
 declare function executeTask(request: TaskRequest, deps: ExecutionDeps): Promise<ResultEnvelope>;
+/**
+ * Execute multiple operations as a batch.
+ *
+ * Classifies steps, resolves node IDs via Phase 1 lookups, batches GraphQL
+ * operations, and returns a {@link ChainResultEnvelope}.
+ */
 declare function executeTasks(requests: Array<{
     task: string;
     input: Record<string, unknown>;

package/dist/index.js

@@ -10,13 +10,21 @@ import {
   getOperationCard,
   listCapabilities,
   listOperationCards
-} from "./chunk-3P3KHWFU.js";
-import "./chunk-Q7RCIK2C.js";
+} from "./chunk-T3L2VDOS.js";
+import "./chunk-H7CLZHRO.js";
+import "./chunk-NQ53ETYV.js";
+import "./chunk-TGL33GEA.js";
+import "./chunk-Q2NW7DJE.js";
 import "./chunk-3DU2WHXF.js";
-import "./chunk-TDABI6C7.js";
+import "./chunk-QRHKAMRY.js";
+import "./chunk-TPQYVCAS.js";
+import "./chunk-7HUKYNI2.js";
+import "./chunk-ZGBVX2VG.js";
+import "./chunk-GQO6BHJV.js";
+import "./chunk-R3CBGJZX.js";
 import {
   createGraphqlClient
-} from "./chunk-HEHONZTO.js";
+} from "./chunk-C2KRRSSX.js";
 
 // src/core/execute/execute-tool.ts
 function createExecuteTool(deps) {

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/core/execute/execute-tool.ts"],"sourcesContent":["import type { ResultEnvelope } from \"../contracts/envelope.js\"\n\ntype ExecuteTaskFn = (request: {\n  task: string\n  input: Record<string, unknown>\n  options?: Record<string, unknown>\n}) => Promise<ResultEnvelope>\n\nexport function createExecuteTool(deps: { executeTask: ExecuteTaskFn }) {\n  return {\n    execute(\n      capabilityId: string,\n      params: Record<string, unknown>,\n      options?: Record<string, unknown>,\n    ): Promise<ResultEnvelope> {\n      const request = {\n        task: capabilityId,\n        input: params,\n        ...(options ? { options } : {}),\n      }\n\n      return deps.executeTask(request)\n    },\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AAQO,SAAS,kBAAkB,MAAsC;AACtE,SAAO;AAAA,IACL,QACE,cACA,QACA,SACyB;AACzB,YAAM,UAAU;AAAA,QACd,MAAM;AAAA,QACN,OAAO;AAAA,QACP,GAAI,UAAU,EAAE,QAAQ,IAAI,CAAC;AAAA,MAC/B;AAEA,aAAO,KAAK,YAAY,OAAO;AAAA,IACjC;AAAA,EACF;AACF;","names":[]}
+{"version":3,"sources":["../src/core/execute/execute-tool.ts"],"sourcesContent":["import type { ResultEnvelope } from \"../contracts/envelope.js\"\n\ntype ExecuteTaskFn = (request: {\n  task: string\n  input: Record<string, unknown>\n  options?: Record<string, unknown>\n}) => Promise<ResultEnvelope>\n\n/**\n * Creates an execute tool suitable for wiring into an AI agent's tool loop.\n *\n * Wraps the execution engine into a simple `{ execute(capabilityId, params) }` shape.\n *\n * @example\n * ```ts\n * const tool = createExecuteTool({\n *   executeTask: (req) => executeTask(req, deps),\n * })\n * const result = await tool.execute(\"repo.view\", { owner: \"aryeko\", name: \"ghx\" })\n * ```\n */\nexport function createExecuteTool(deps: { executeTask: ExecuteTaskFn }) {\n  return {\n    execute(\n      capabilityId: string,\n      params: Record<string, unknown>,\n      options?: Record<string, unknown>,\n    ): Promise<ResultEnvelope> {\n      const request = {\n        task: capabilityId,\n        input: params,\n        ...(options ? { options } : {}),\n      }\n\n      return deps.executeTask(request)\n    },\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqBO,SAAS,kBAAkB,MAAsC;AACtE,SAAO;AAAA,IACL,QACE,cACA,QACA,SACyB;AACzB,YAAM,UAAU;AAAA,QACd,MAAM;AAAA,QACN,OAAO;AAAA,QACP,GAAI,UAAU,EAAE,QAAQ,IAAI,CAAC;AAAA,MAC/B;AAEA,aAAO,KAAK,YAAY,OAAO;AAAA,IACjC;AAAA,EACF;AACF;","names":[]}