Tools
Typesafe
By OpenClaw Tool Plugin exposing TypeSafe System One judgments with SecretRef-safe credentials and bundled Skill
Install
npm install --omit=devREADME
# OpenClaw TypeSafe Plugin
[](../../actions/workflows/ci.yml)
Independent handoff repository for a **standard OpenClaw Tool Plugin plus bundled TypeSafe Skill**. The plugin registers `typesafe_system_one`, calls TypeSafe `POST /v1/systemone`, and returns judgments only. It is intentionally **not** an OpenClaw model provider.
## Status
This repository is **GitHub-ready**: it has pinned dependencies/tooling, committed build output required by OpenClaw Git installs, CI, a manual non-publishing release-artifact workflow, exact package inventory/credential gates, and disposable Git-tag installation proof. It is still not a production deployment: no remote/tag/GitHub Release exists and no real Gateway has been changed. See `STATUS.md` and `QA.md`.
## Why Tool Plugin + Skill
- TypeSafe System One evaluates typed questions over supplied state; it does not supply OpenClaw chat/completion turns, streaming, context management, or provider model routing.
- The plugin tool owns the deterministic runtime boundary: schema validation, SecretRef-resolved credential, HTTPS, timeout/retry, response shaping, and redacted diagnostics.
- The bundled Skill preserves TypeSafe's upstream guidance for deciding when and how an Agent should use the tool.
- The tool never executes the action suggested by a judgment. Authorization and side effects remain in existing deterministic code and OpenClaw approval controls.
## Repository map
- `HANDOFF.md` — next Agent starts here.
- `docs/API-CONTRACT.md` — exact tool/API contract.
- `docs/ARCHITECTURE.md` — components and trust boundaries.
- `docs/SECURITY.md` — SecretRef, logging, and action boundary.
- `docs/DEPLOYMENT.md` — cross-Gateway release/rollback/key rotation runbook.
- `docs/SANDBOX-AND-ACP.md` — access paths and gates.
- `docs/ACCEPTANCE-CRITERIA.md` — acceptance matrix.
- `src/` and `tests/` — implementation and fully mocked local test suites.
- `skills/typesafe-ai/` — upstream MIT Skill snapshot and license.
- `scripts/` — verification gates, live disposable scripts, release-artifact generator.
- `evidence/` — committed sanitized verification evidence and release artifacts.
## Install an immutable version
Replace `<owner>` and `<tag>` with the reviewed GitHub owner and immutable release tag. Arbitrary Git installs require explicit source/capability consent:
```bash
openclaw plugins install git:github.com/<owner>/openclaw-typesafe-plugin@<tag> \
--force --accept-capabilities
```
OpenClaw 2026.9.4 clones and checks out the ref, then runs `npm install --omit=dev --ignore-scripts`; it does **not** build TypeScript. Tagged commits therefore contain reviewed `dist/` output, and CI verifies it is current. Evidence: `docs/evidence/OFFICIAL-GIT-INSTALL-2026.9.4.md`.
Alternatively, download the `openclaw-typesafe-plugin-<version>.tgz` asset and `SHA256SUMS.txt` from the same GitHub Release, verify before install, then use the managed npm-pack path:
```bash
shasum -a 256 -c SHA256SUMS.txt
openclaw plugins install npm-pack:./openclaw-typesafe-plugin-<version>.tgz \
--force --accept-capabilities
```
Configure a SecretRef (never a plaintext key), enable, validate, and inspect runtime registration:
```bash
openclaw config set plugins.entries.typesafe-ai.config.apiKey \
--ref-source store --ref-provider default --ref-id TYPESAFE_API_KEY
openclaw plugins enable typesafe-ai --accept-capabilities
openclaw config validate --json
openclaw plugins inspect typesafe-ai --runtime --json
```
Expected runtime evidence: `status: "loaded"`, `imported: true`, and `toolNames: ["typesafe_system_one"]`. Run these commands only under the target Gateway's approved change control; repository tests always use isolated `.tmp` state.
## Local development
The committed lockfile pins the project-local OpenClaw SDK/CLI to `2026.9.4`. Reproduce the verified local checks with:
```bash
npm ci
npm run typecheck
npm test
npm run build
npm run build:check # rebuild + require committed dist to stay unchanged
npm run plugin:build # build + generate manifest metadata via `openclaw plugins build` (isolated)
npm run plugin:check # build + stale-metadata gate + `plugins validate` (must exit 0)
npm run plugin:validate # full fatal pipeline: clean-room ci/build + authoring gates + manifest merge + pack + disposable install + discovery
npm run package:verify # exact npm-pack allowlist + credential-shaped-value scan
npm run git-source:smoke # bare repo/tag -> actual OpenClaw git:file:// install, isolated under .tmp
npm run workflow:check # YAML + read-only/no-publish policy checks
```
`openclaw.plugin.json` is **generated** by `openclaw plugins build` from the `defineToolPlugin` entry source (id, name, description, version, configSchema, activation, contracts.tools). Hand-authored contract fields (`configContracts.secretInputs`, `skills`, `toolMetadata`) survive generation as a merge and are pinned by `tests/manifest.test.ts` + `scripts/assert-manifest-merge.mjs`.
`dist/` is intentionally tracked. Do not add a build lifecycle hook: OpenClaw Git installs disable lifecycle scripts and omit the TypeScript dev dependency. Build locally, commit the changed `dist/`, and let `build:check` reject drift.
`npm run plugin:validate` never uses the current Life Gateway. Every OpenClaw invocation is wrapped by `scripts/validate-isolated.sh`, which confines HOME, config, state, XDG paths, and temporary files under the ignored repository `.tmp/` directory.
## Live verification (disposable, real network)
Two scripts drive the **production path** — the compiled `dist` entry registered exactly as the Gateway registers it, `tool.execute()` performing the real `POST /v1/systemone` with the full validation/redaction stack:
```bash
npm run build
# Success path: requires TYPESAFE_API_KEY injected into the environment by the
# protected-secret/exec mechanism. Never passed as argv, never read from files.
NODE_USE_ENV_PROXY=1 https_proxy="$HTTPS_PROXY" http_proxy="$HTTP_PROXY" npm run live:smoke
# Auth-rejection path: fixed public fake key; no secret involved.
NODE_USE_ENV_PROXY=1 https_proxy="$HTTPS_PROXY" http_proxy="$HTTP_PROXY" npm run live:401
```
Hard rules (enforced by the scripts, see `scripts/live-common.mjs`):
- The key enters **only** via `process.env.TYPESAFE_API_KEY` (protected-secret injection, egress-allowlisted to `api.typesafe.ai`). It is never printed, logged, persisted, or passed as a command argument. Missing injection is a precise blocker (exit 2) — the scripts never prompt for a key.
- Request state is a fixed, public, disposable constant with exactly one `noul` question — no user data leaves the machine beyond that string.
- Only sanitized summaries are printed (status, model, answer shape, usage, attempt counts, timings); response bodies and request headers are never captured. Proxy variables are set lowercase from the host-provided uppercase values (`https_proxy="$HTTPS_PROXY" http_proxy="$HTTP_PROXY"`), never any credential sentinel.
- `live:401` proves: real HTTP 401 from a fixed fake key, exactly one attempt (`maxRetries=0` plus a status-counting fetch wrapper), the exact generic agent-visible message, allowlisted log fields, no body/key material, and loud failure on any unexpected success.
Sanitized run records: `evidence/live-smoke-2026-09-21.txt`, `evidence/live-401-2026-09-21.txt`.
## Release evidence artifacts
`evidence/release/2026-09-21/` holds the built-once installable artifact and its verification trail, generated by `scripts/generate-release-artifacts.mjs` from a clean source commit via a `git archive` clean room (`npm ci --offline` → build → `npm pack`):
- `openclaw-typesafe-plugin-0.1.0.tgz` + `SHA256SUMS.txt` (`shasum -a 256 -c SHA256SUMS.txt`)
- `BUILD-MANIFEST.json` — source commit, environment, per-artifact digests, rebuild/verify commands
- `ENVIRONMENT.json` — node/npm/git/OS/OpenClaw CLI/TypeScript versions
- `sbom-spdx.json` (SPDX 2.3) and `sbom-cyclonedx.json` (CycloneDX 1.5) — offline SBOMs scoped to the shipped package plus direct dependencies; the committed `package-lock.json` remains the authoritative full dependency tree
- `PROVENANCE.json` — in-toto Statement v1 / SLSA provenance v1, **unsigned local attestation**; nothing is published or signed
**Two-phase evidence commits.** Artifact digests cannot be stored inside the commit they attest (circular self-reference). This repository therefore uses a source commit `S` (all code/docs; the tree the artifact was built from) followed by an evidence commit `E` that adds **only evidence paths**. `git diff S..E` shows evidence-only changes, and `BUILD-MANIFEST.json` / `PROVENANCE.json` pin `S` (decision `D13`).
`.github/workflows/release-artifacts.yml` is an independent, manual-only (`workflow_dispatch`) build. It runs the pre-release gates and uploads a review artifact containing the tarball, SHA256, SPDX 2.3, CycloneDX 1.5, environment/build manifest, and unsigned in-toto/SLSA provenance. It has read-only repository permission and contains no publish, tag, push, registry, or GitHub Release step.
## Intended configuration (documentation only)
```json5
{
plugins: {
entries: {
"typesafe-ai": {
enabled: true,
config: {
apiKey: { source: "store", provider: "default", id: "TYPESAFE_API_KEY" },
model: "jev-1.13.0"
}
},
acpx: { config: { pluginToolsMcpBridge: true } }
}
}
}
```
Do not paste a key into configuration. Operations pre-provisions `TYPESAFE_API_KEY` in each Gateway's shared secret store.
## License
Project scaffold: MIT. Bundled Skill licensing and source are retained in `skills/typesafe-ai/LICENSE` and `docs/SOURCES.md`.
tools
Comments
Sign in to leave a comment