@open-agent-toolkit/cli 0.2.4 → 0.2.6

package/assets/skills/explainer-kit/references/destination-contract.md

@@ -0,0 +1,94 @@
+# S3 static destination contract
+
+The `s3-static` connector publishes only files declared as built artifacts in a
+validated manifest. Publishing is human-gated:
+
+```bash
+node scripts/publish.mjs \
+  --request /path/to/publish-request.json \
+  --receipt /path/to/publish-receipt.json \
+  --confirm-publish
+```
+
+The request uses `explainer-kit.publish-request/v1`. Credentials come only from
+the standard AWS credential chain or the request's optional profile. Never put
+access keys, secret keys, session tokens, or SSO tokens in a request.
+
+## Corresponding roots
+
+`s3Uri` and `publicBaseUrl` must identify corresponding roots. Both are
+normalized without trailing slashes. For a path `P` relative to `siteRoot`, the
+connector writes `<s3Uri>/P` and verifies `<publicBaseUrl>/P`.
+
+For example:
+
+| Input                   | Value                                                           |
+| ----------------------- | --------------------------------------------------------------- |
+| `siteRoot`              | `/tmp/run/site`                                                 |
+| manifest `renderedPath` | `site/initiatives/demo/index.html`                              |
+| `s3Uri`                 | `s3://example-bucket/published`                                 |
+| `publicBaseUrl`         | `https://cdn.example.com/published`                             |
+| object                  | `s3://example-bucket/published/initiatives/demo/index.html`     |
+| public URL              | `https://cdn.example.com/published/initiatives/demo/index.html` |
+
+Use explicit `index.html` URLs. Directory redirects are not portable evidence.
+The destination must serve uploaded bytes at the corresponding public path.
+
+## Safety and ordering
+
+The connector validates the request, manifest, paths, hashes, and duplicate
+site-relative paths before network access. It then:
+
+1. uploads a sentinel whose path contains the run ID and a random 128-bit
+   suffix;
+2. verifies the sentinel with `head-object`;
+3. fetches that exact sentinel through the public root;
+4. deletes only that sentinel;
+5. uploads or idempotently skips each declared artifact;
+6. verifies object metadata, content type, and SHA-256 of the exact response
+   bytes from each public artifact URL; and
+7. atomically writes `explainer-kit.publish-receipt/v1`.
+
+If public sentinel verification fails, no artifact is uploaded. The connector
+attempts sentinel cleanup and emits no successful receipt.
+
+Publishing is additive. The implementation uses individual `put-object`,
+`head-object`, and sentinel-only `delete-object` operations. It never performs
+root-wide synchronization, never passes a delete flag, never walks or uploads
+undeclared files, and never deletes an artifact object. Existing declared
+objects with matching hash and metadata are skipped; changed declared objects
+may be replaced.
+
+## Metadata
+
+Every upload sets metadata explicitly:
+
+| File    | Content type                                      |
+| ------- | ------------------------------------------------- |
+| `.html` | `text/html; charset=utf-8`                        |
+| `.json` | `application/json`                                |
+| `.css`  | `text/css; charset=utf-8`                         |
+| `.js`   | `text/javascript; charset=utf-8`                  |
+| `.svg`  | `image/svg+xml`                                   |
+| `.txt`  | `text/plain; charset=utf-8`                       |
+| other   | manifest media type or `application/octet-stream` |
+
+Artifacts use `Cache-Control: public, max-age=300`. The connector stores the
+SHA-256 digest as object metadata for idempotency and verifies content type,
+cache control, and digest after upload. Public verification hashes response
+bytes without text decoding, so binary artifacts and stale wrong-byte 200
+responses are covered.
+
+## Failures and retries
+
+Authentication and permission failures stop immediately. The connector does
+not run `aws sso login`, retry with another profile, expose AWS diagnostics, or
+persist credentials. Refresh credentials separately and rerun after approval.
+
+Only transient individual object-operation failures receive bounded retries.
+Input, authorization, root-correspondence, metadata, and public-verification
+failures are not retried. A failed publish preserves the local package.
+
+Public roots must be credential-free HTTPS URLs with no username, password,
+query, or fragment. Invalid roots fail before AWS or HTTP operations and are
+never persisted in receipts.

package/assets/skills/explainer-kit/references/extension-contract.md

@@ -0,0 +1,71 @@
+# Wrapper extension contract
+
+V1 freezes one destination-neutral extension seam:
+
+1. **Pre-resolution:** the caller resolves presets, private source systems,
+   accounts, and destination topology without exposing them as public config.
+2. **`ExplainerRunRequestV1`:** the caller translates only the inputs required
+   by `explainer-kit.run-request/v1`.
+3. **Core run:** the caller invokes `runExplainer(request, options)` once. The
+   core owns validation, fact-base processing, content, theme, render, QA, and
+   run records.
+4. **Manifest consumption:** the caller accepts only
+   `explainer-kit.manifest/v1`, verifies its run, recipe, and slug identity, and
+   reads built artifact paths from the manifest.
+5. **Post-run linking:** the caller may create companion notes, synchronize
+   external documents, or maintain private links from manifest and optional
+   publish-receipt data.
+
+Private wrappers may retain presets, vault conventions, Google Docs behavior,
+and personal destinations around this seam. Those values are wrapper-owned;
+they are not OAT config keys and must not be discovered by the core.
+
+## Frozen v1 boundary
+
+The versioned request, artifact package, manifest, build record, durability
+request, publish request, and publish receipt are the public boundary. V1 has
+no plugin registry and no mid-pipeline callback API for private destinations.
+Provider-neutral callbacks already documented by the core remain explicit run
+options; they do not transfer stage ownership to a wrapper.
+
+V1 readers reject unsupported contract majors and identity mismatches rather
+than guessing. Wrappers should preserve unknown future versions for diagnosis,
+stop before post-processing, and migrate deliberately.
+
+The compatibility smoke fixture at
+`tools/smoke/explainer-kit/wrapper-compatibility.test.mjs` proves this sequence
+with the actual core. It uses sanitized private-wrapper inputs and is not a
+substitute for the operator-owned release-candidate gate.
+
+Release-candidate execution requires the retained tarball directory explicitly:
+
+```bash
+# Pre: resolve private inputs and write the external run request.
+node tools/release/run-explainer-rc.mjs \
+  --rc-manifest /path/to/acceptance/rc.json \
+  --artifacts-dir /path/to/retained/explainer-kit-rc \
+  --entry scripts/run.mjs \
+  --record /path/to/acceptance/private-wrapper-execution.json \
+  -- --request /path/to/private/request.json
+```
+
+The packaged CLI stdout contract is exactly one complete JSON result document.
+The document may be pretty-printed across lines; progress text and
+line-delimited JSON are not part of this machine framing. The RC runner parses
+the complete document, then binds the request, child-reported manifest, and core
+run ID. It binds a receipt only when the packaged child itself reports that
+output. The sanitized record does not store paths, argument values, credentials,
+or private content.
+
+After the core command returns, the wrapper performs its post-run publication
+and linking work. It retains the immutable core manifest as
+`private-wrapper-manifest.json`, the complete `PublishReceiptV1` as
+`private-wrapper-publish-receipt.json`, and its sanitized wrapper result as
+`private-wrapper-result.json`. The wrapper result repeats canonical hashes for
+the request, manifest, and post-run receipt.
+
+The wrapper acceptance stage reads those post-run files separately. It
+validates the closed receipt contract, every manifest artifact/hash and
+destination, the run-unique sentinel, the manifest hash, and the core run ID
+against `private-wrapper-execution.json`. Repeating a matching hash cannot make
+a foreign or stale receipt attributable to the packaged run.

package/assets/skills/explainer-kit/references/fact-base-contract.md

@@ -0,0 +1,119 @@
+# Fact-base processing contract
+
+`processFactBase(binding, options)` produces one
+`explainer-kit.fact-base/v1` record plus processing diagnostics. It has no
+provider-specific dispatch logic and reads no ambient configuration.
+
+## Result
+
+The function resolves to:
+
+```js
+{
+  factBase, // valid explainer-kit.fact-base/v1
+  checks,   // consistency/freshness diagnostics
+  critic,   // critic invocation and provenance metadata
+}
+```
+
+All claims are cited. Claims that cannot be reconciled remain in
+`unresolvedClaims` with one of the contract's closed reason values.
+
+## Supplied mode
+
+Use:
+
+```js
+await processFactBase({
+  mode: 'supplied',
+  freshnessPolicy: 'live-wins',
+  factBase,
+});
+```
+
+The processor validates the supplied v1 record, verifies unique source and
+claim IDs, verifies that every citation names a declared source, verifies that
+every override names a confirmed claim, and compares `generatedAt` plus each
+available source `observedAt` with the freshness window. Staleness produces a
+warning; structural or citation inconsistency rejects the input.
+
+Supplied mode never invokes the adversarial critic. Its `critic` result is
+`{ invoked: false, reason: 'supplied-mode-lightweight-check-only' }`.
+
+## Federated mode
+
+Each source document contains a schema-compatible source and extracted claims:
+
+```js
+{
+  mode: 'federated',
+  freshnessPolicy: 'live-wins',
+  sourceDocuments: [{
+    source: {
+      id,
+      kind,
+      locator,
+      revision,
+      hash,
+      observedAt,
+      authoritativeFor,
+    },
+    claims: [{ id, text, locator }],
+  }],
+  overrides: [{ claimId, decision, confirmedAt }],
+}
+```
+
+For conflicting text under one claim ID, an `authoritativeFor` declaration
+wins first. Otherwise the newest `observedAt` wins. A tie remains
+`contradictory`. Operator overrides take final precedence, produce an
+`overridden` claim, remain explicit in `overrides`, and suppress critic
+findings for that claim.
+
+Federated processing requires `options.critic`, an asynchronous,
+provider-neutral callback. The callback receives only data:
+
+```js
+async function critic({ freshnessPolicy, sources, claims, overrides }) {
+  return {
+    criticId: 'stable-callback-id',
+    executedAt: new Date().toISOString(),
+    findings: [
+      {
+        claimId: 'status',
+        classification: 'contradictory',
+        text: 'The status sources disagree.',
+        sourceIds: ['snapshot', 'live'],
+      },
+    ],
+  };
+}
+```
+
+The seam deliberately contains no provider, model, command, or dispatch
+field. The caller owns critic execution; the core only invokes the callback
+and integrates its returned data.
+
+## Critic provenance
+
+Every federated invocation adds one source:
+
+```js
+{
+  id: `critic:${criticId}`,
+  kind: 'other',
+  locator: `critic-callback:${criticId}`,
+  hash: canonicalHash(criticResult),
+  observedAt: executedAt,
+}
+```
+
+The result's `critic` metadata repeats the stable critic ID, execution time,
+source ID, and canonical result hash. Integrated findings cite both this
+synthetic critic source and every declared source named by the finding. This
+makes the critic's contribution auditable without exposing or depending on a
+provider-specific implementation.
+
+Critic classifications map directly to unresolved-claim reasons. A finding
+removes a previously confirmed claim and creates an unresolved claim, or
+updates an already unresolved claim while preserving its existing citations.

package/assets/skills/explainer-kit/schemas/build-record.schema.json

@@ -0,0 +1,92 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "explainer-kit.build-record/v1",
+  "title": "BuildRecordV1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "runId",
+    "renderStrategy",
+    "startedAt",
+    "stages",
+    "outcome"
+  ],
+  "properties": {
+    "schemaVersion": { "const": "explainer-kit.build-record/v1" },
+    "runId": { "type": "string", "minLength": 1 },
+    "renderStrategy": { "enum": ["default-only", "user-switchable"] },
+    "startedAt": { "type": "string", "format": "date-time" },
+    "completedAt": { "type": "string", "format": "date-time" },
+    "stages": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/stage" },
+      "minItems": 1
+    },
+    "outcome": {
+      "enum": ["built-durable", "built-not-durable", "failed", "incomplete"]
+    }
+  },
+  "$defs": {
+    "safeRelativePath": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^(?!/)(?!.*(?:^|/)\\.\\.(?:/|$)).+$"
+    },
+    "error": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["code", "message", "recovery"],
+      "properties": {
+        "code": { "type": "string", "minLength": 1 },
+        "message": { "type": "string", "minLength": 1 },
+        "recovery": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 },
+          "minItems": 1
+        }
+      }
+    },
+    "stage": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "status", "outputPaths", "warnings"],
+      "properties": {
+        "id": {
+          "enum": [
+            "validate",
+            "fact-base",
+            "content",
+            "theme",
+            "render",
+            "qa",
+            "durability",
+            "publish"
+          ]
+        },
+        "status": {
+          "enum": [
+            "pending",
+            "running",
+            "passed",
+            "warned",
+            "failed",
+            "skipped"
+          ]
+        },
+        "startedAt": { "type": "string", "format": "date-time" },
+        "completedAt": { "type": "string", "format": "date-time" },
+        "outputPaths": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/safeRelativePath" },
+          "uniqueItems": true
+        },
+        "warnings": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "error": { "$ref": "#/$defs/error" }
+      }
+    }
+  }
+}

package/assets/skills/explainer-kit/schemas/durability-evidence.schema.json

@@ -0,0 +1,53 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "explainer-kit.durability-evidence/v1",
+  "title": "DurabilityEvidenceRequestV1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "manifestPath", "evidence"],
+  "properties": {
+    "schemaVersion": {
+      "const": "explainer-kit.durability-evidence/v1"
+    },
+    "manifestPath": { "type": "string", "minLength": 1 },
+    "evidence": {
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["kind", "repoRoot", "commit", "paths"],
+          "properties": {
+            "kind": { "const": "commit" },
+            "repoRoot": { "type": "string", "minLength": 1 },
+            "commit": {
+              "type": "string",
+              "pattern": "^[a-f0-9]{7,64}$"
+            },
+            "paths": {
+              "type": "array",
+              "items": { "$ref": "#/$defs/safeRelativePath" },
+              "minItems": 1,
+              "uniqueItems": true
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["kind", "receiptPath"],
+          "properties": {
+            "kind": { "const": "publish" },
+            "receiptPath": { "type": "string", "minLength": 1 }
+          }
+        }
+      ]
+    }
+  },
+  "$defs": {
+    "safeRelativePath": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^(?!/)(?!.*(?:^|/)\\.\\.(?:/|$)).+$"
+    }
+  }
+}

package/assets/skills/explainer-kit/schemas/fact-base.schema.json

@@ -0,0 +1,129 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "explainer-kit.fact-base/v1",
+  "title": "FactBaseV1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "generatedAt",
+    "mode",
+    "freshnessPolicy",
+    "sources",
+    "claims",
+    "unresolvedClaims",
+    "overrides"
+  ],
+  "properties": {
+    "schemaVersion": { "const": "explainer-kit.fact-base/v1" },
+    "generatedAt": { "type": "string", "format": "date-time" },
+    "mode": { "enum": ["supplied", "federated"] },
+    "freshnessPolicy": { "const": "live-wins" },
+    "sources": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/source" },
+      "minItems": 1,
+      "uniqueItems": true
+    },
+    "claims": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/claim" },
+      "uniqueItems": true
+    },
+    "unresolvedClaims": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/unresolvedClaim" },
+      "uniqueItems": true
+    },
+    "overrides": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/override" },
+      "uniqueItems": true
+    }
+  },
+  "$defs": {
+    "hash": {
+      "type": "string",
+      "pattern": "^sha256:[a-f0-9]{64}$"
+    },
+    "source": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "kind", "locator", "hash"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "kind": {
+          "enum": ["file", "directory", "git", "github", "session", "other"]
+        },
+        "locator": { "type": "string", "minLength": 1 },
+        "role": { "type": "string", "minLength": 1 },
+        "sourceSetId": { "type": "string", "minLength": 1 },
+        "revision": { "type": "string", "minLength": 1 },
+        "hash": { "$ref": "#/$defs/hash" },
+        "observedAt": { "type": "string", "format": "date-time" },
+        "authoritativeFor": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 },
+          "uniqueItems": true
+        }
+      }
+    },
+    "citation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["sourceId", "locator"],
+      "properties": {
+        "sourceId": { "type": "string", "minLength": 1 },
+        "locator": { "type": "string", "minLength": 1 }
+      }
+    },
+    "claim": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "text", "status", "citations"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "text": { "type": "string", "minLength": 1 },
+        "status": { "enum": ["confirmed", "overridden"] },
+        "citations": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/citation" },
+          "minItems": 1,
+          "uniqueItems": true
+        }
+      }
+    },
+    "unresolvedClaim": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "text", "reason", "citations"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "text": { "type": "string", "minLength": 1 },
+        "reason": {
+          "enum": [
+            "contradictory",
+            "stale",
+            "missing-evidence",
+            "needs-confirmation"
+          ]
+        },
+        "citations": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/citation" },
+          "uniqueItems": true
+        }
+      }
+    },
+    "override": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["claimId", "decision", "confirmedAt"],
+      "properties": {
+        "claimId": { "type": "string", "minLength": 1 },
+        "decision": { "type": "string", "minLength": 1 },
+        "confirmedAt": { "type": "string", "format": "date-time" }
+      }
+    }
+  }
+}