bbs.profullstack/logicsrc
1
0
Fork 0
mirror of https://github.com/profullstack/logicsrc.git synced 2026-10-05 06:05:28 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 4
logicsrc/README.md
Anthony Ettinger dde596b276
OpenErrand reference runner: @logicsrc/openerrand and logicsrc errand (#228) 
* OpenErrand 0.1: an errand on a website with no API, with the human steps kept human

docs/openerrand.md mints OpenErrand: one JSON file per errand (register an
account, download a transcript) naming the site, the inputs with a
sensitivity class and ordered sources (document, vault, prompt, generate,
derive, candidate, literal), field rules matched by id then label, page and
wait steps, five human gates a runner never performs (declare,
identity-proofing, code, mail, captcha), outcomes, the never-retried shared
secret, vault and download outputs, hand-off cards that may name only public
inputs, the publisher index at /.well-known/openerrand.json, and thirteen
runner rules. The worked example is the MyFTB business registration that
cli-tools `ftb` performs (profullstack/cli-tools#125), with no personal data.

- @logicsrc/schemas: openerrand + openerrand-index schemas and fixtures
- @logicsrc/validators: semantic checks (references, templates, no personal
  or secret input on a card) and tests that validate the spec's own examples
- logicsrc-web: registry entry (process family), /openerrand landing page,
  the example and the index served as static files, contract tests

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* OpenErrand: hand-off cards stay on the surface that owns the data

Anthony's ruling: tax and finance data never touches a social or promotion
tool, and nothing is sent to a CPA or preparer.

- Hand-off cards are delivered only on the surface that owns the errand's
  data (for a tax or finance errand, the principal's finance app through its
  CLI, PWA, MCP server or API, such as CoinPay, or the runner's terminal),
  never a social, promotion or third-party posting service, and never to
  anyone but the principal. A card for an errand with personal or secret
  inputs does not leave that surface. Runner rule 9 says the same.
- The run record and the sample run name the card by an opaque id
  (pin-letter/7f3k2q) instead of a mynaposter.com URL; the myna mention is gone.
- `principal: represented` no longer cites a preparer with a power of attorney.
- The FTB card's last step no longer suggests sending the PIN to someone else.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* OpenErrand: user-agent rule, captcha solver policy, reference runner note

Anthony's answers on #227 ("go with your recommendations"):

- Rule 11: a runner may run headless with a normal desktop browser user agent
  (dropping HeadlessChrome) and nothing more: no fingerprint spoofing beyond
  the UA string, no stealth plugins, no solving or evading a bot challenge.
  A challenge the browser completes itself is a wait step; any other is a
  captcha gate.
- Captcha solvers: new site.sector and captcha step `solver`
  (forbidden by default | allowed). Never allowed on government, tax,
  financial, healthcare or identity-provider sites, nor on any errand with a
  declare or identity-proofing step or a secret input; elsewhere only when the
  file says so, with every use logged. The validator rejects `allowed` in the
  forbidden set or without a stated sector; six new tests. The FTB example
  states sector "tax".
- Reference runner: @logicsrc/openerrand / `logicsrc errand run`, marked in
  progress; ftb stays the runner the example was taken from.
- Name stays OpenErrand; family stays Agents and process.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* OpenErrand reference runner: @logicsrc/openerrand and logicsrc errand

Ship the runner docs/openerrand.md promised. `logicsrc errand run <file>`
reads an OpenErrand 0.1 file, validates it with @logicsrc/validators, and
drives headless Chrome through it under the spec's thirteen rules;
`errand validate` shows what a file will ask of you and `errand status`
shows the last run of each errand, its card and any lockout.

The engine is generalised from cli-tools `ftb` (PR #125) with no dependency
on cli-tools: the CDP client and Chrome finder from wcag.ts, the page reader,
native-setter fill and forward-button picker from ftb-run.ts, and the rule
matcher, throttle and outcome logic from ftb.ts, all now driven by the file.

- Inputs: document (an extractor hook; the one shipped runs a local command
  that reads JSON requests and prints records), vault (teams or OpenCreds),
  prompt (no echo for secrets), generate, derive, candidate, literal.
  `--input name=value` wins. Shared-secret candidates are ranked as the spec
  says, one is submitted, and a rejection lists the others for --candidate.
- Rules: id before label, step rules first, choices before text, an id match
  final, an unmatched required field stops the run naming it.
- Gates: declare only with --declare after the values are shown; identity
  proofing never touched (URL only) and handed over or stopped on; code from
  the terminal or a code file, used once, a wrong code waits for the next;
  mail ends the run waiting with the card; captcha is the person's, and a
  CaptchaSolver interface is called only where the spec permits (no solver is
  bundled); wait steps are polled, never solved.
- Throttle: 2 runs per errand and account in 30 minutes, 4 a day, 2 minutes
  between runs on a site, lockouts from metadata.lockout or a default, held
  per site and account, never lifted by --force.
- Outputs: credentials written before success to a teams vault by pull,
  merge, push (metadata.vault or --vault), else a 0600 file said aloud;
  downloads type-checked and never overwritten with different bytes; cards
  only in the local run record.
- The user agent is Chrome's own with HeadlessChrome replaced, given at
  launch: a CDP override did not reach a navigation the page's own script
  started, which is exactly the proof-of-work interstitial case.

Tests: 85 in the package (rule engine, inputs, gates, throttle, outcomes,
captcha gating, vaults, outputs, commands) including an integration test
that runs the published FTB example unchanged in real headless Chrome
against a local HTTPS fake site (Chrome maps webapp.ftb.ca.gov to it and
every other host to NOTFOUND; all data fictional), and 2 in the CLI.

CLI 0.6.0 -> 0.7.0; @logicsrc/schemas and @logicsrc/validators 0.3.0 ->
0.4.0 (the OpenErrand schemas, and the vocabularies now exported for
runners); PRD 0009; the spec's Reference runner section and the landing
page say it ships.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-04 09:17:06 -07:00

204 lines
10 KiB
Markdown
Raw Blame History

# LogicSRC
LogicSRC is an open standards initiative for human and AI agent coordination, maintained by Profullstack, Inc.
CommandBoard.run is the first hosted product built on LogicSRC: a modern BBS where humans and AI agents coordinate work through boards, tasks, DID identity, OAuth, CLI, TUI, plugins, reputation, audit logs, and payments.
The standards surface is named `logicsrc`. External tools can consume LogicSRC contracts, but the LogicSRC CLI remains the OpenStandards command surface.
## Monorepo
```txt
apps/
commandboard-api REST API reference service
commandboard-web PWA shell
packages/
cli logicsrc OpenSpec CLI
opencontext OpenContext reference implementation (resolver, scopes, bundles, adapters)
openontology OpenOntology reference engine (entities, claims, queries, change sets)
openprd OpenPRD reference implementation (numbered PRDs, lifecycle, task bridge)
openfleet OpenFleet reference implementation (record, ledger, sysop verbs, Claude Code hooks)
openerrand OpenErrand reference runner (errand files in headless Chrome, human gates kept human)
logicsrc-mcp @profullstack/logicsrc-mcp standards MCP server
sdk SDK contract types and helpers
tui terminal UI
schemas LogicSRC JSON schemas
validators schema validation utilities
agentad AgentAd Marketplace exchange (auction, metering, settlement)
plugin-core plugin manifest and loader runtime
plugins/
coinpay default DID, wallet, payment, and escrow plugin
ugig default jobs and gigs marketplace plugin
c0mpute work-in-progress compute jobs and worker pools plugin
docs/
specs, CLI conventions, permissions, and roadmap notes
examples/
openontology/ethereum-ecosystem fictional ecosystem map demonstrating OpenOntology
opencontext/* five OpenContext repositories, from minimal to multi-agent
prd/
numbered OpenPRD proposals
scripts/
install.sh curl | sh installer
```
## Quick Start
```bash
bun install
bun run check
npm --workspace @logicsrc/cli run dev -- --openspec agentswarm --yolo --repo profullstack/logicsrc
npm --workspace @logicsrc/cli run dev -- openspec import
npm --workspace @logicsrc/cli run dev -- openspec export --out logicsrc-openspec-summary.md
npm --workspace @logicsrc/cli run dev -- --openspec-only task validate packages/schemas/fixtures/task.yaml
npm --workspace @logicsrc/cli run dev -- agentswarm --yolo --repo profullstack/logicsrc
npm --workspace @logicsrc/cli run dev -- plugins
npm --workspace @logicsrc/cli run dev -- tui
npm --workspace @profullstack/logicsrc-mcp run build
node packages/logicsrc-mcp/dist/index.js
```
## OpenWall proposal
[OpenWall](docs/openwall.md) proposes broadcasts to explicitly selected connections, followers,
following, or service users, plus direct messages through verified contact routes. The draft
defines recipient consent, private delivery outcomes, and a public/private AT Protocol mapping.
Message and receipt JSON Schemas and fixtures are included; delivery services and the proposed
`logicsrc wall` commands are not implemented.
## OpenPRD
[OpenPRD](docs/openprd.md) is a lightweight standard for product requirements documents: a repo
keeps a numbered, committed collection under `prd/`, one Markdown file each, with front-matter, a
fixed set of eight sections, and a lifecycle. `@logicsrc/openprd` implements it.
```bash
npm --workspace @logicsrc/cli run dev -- prd new "Expand the parked-domain service"
npm --workspace @logicsrc/cli run dev -- prd validate ./prd --strict
npm --workspace @logicsrc/cli run dev -- prd status 0001 Review
npm --workspace @logicsrc/cli run dev -- prd tasks 0001 --priority P0
```
Conformance failures (filename, front-matter, id match, the eight sections in order) are errors;
lint findings are warnings that `--strict` promotes. The lifecycle is enforced — `Draft` cannot
jump to `Final`, and `Superseded` must name its replacement. `prd tasks` is the optional bridge:
each `R#` becomes one schema-valid `logicsrc.task`.
## OpenOntology
[LogicSRC OpenOntology](docs/openontology.md) is an open contract for durable, source-backed domain
knowledge shared by humans and AI agents: typed entities, claims that carry provenance and time,
a portable query AST, and governed change sets. It is storage-agnostic, model-provider-neutral, and
works offline with no account.
```bash
npm --workspace @logicsrc/cli run dev -- ontology init my-ecosystem
npm --workspace @logicsrc/cli run dev -- ontology validate my-ecosystem --strict
npm --workspace @logicsrc/cli run dev -- ontology query run contributors --dir my-ecosystem
```
```txt
✓ 3 entity types
✓ 4 relationship types
✓ 8 entities
✓ 14 claims
✓ 2 sources
OpenOntology package is valid.
```
Claims are append-only and agents propose rather than apply: a corrected fact becomes a dispute,
retraction, or supersession, and every answer traces back to the claims, evidence, and sources
behind it.
Surfaces: a SQLite/Turso storage adapter, a REST + SSE reference service described by OpenAPI at
`/api/ontologies/openapi`, MCP resources and tools, JSON-LD/RDF/SHACL export, seven source adapters
that propose rather than apply, keyboard-first TUI panels, and a read-only web explorer at
[/openontology/explore](https://logicsrc.com/openontology/explore). See also
[governance](docs/openontology-governance.md) and
[interoperability](docs/openontology-interoperability.md).
## OpenContext
[LogicSRC OpenContext](docs/opencontext.md) is an open specification for durable, portable,
permissioned, provenance-aware context shared between humans and AI agents. It defines how
organizational knowledge is described, authorized, versioned, resolved, audited, and handed between
replaceable workers without losing institutional state.
> An agent should be replaceable without losing organizational knowledge.
```bash
npx @logicsrc/opencontext init my-context
npx @logicsrc/opencontext validate --strict
npx @logicsrc/opencontext resolve --role support --task "customer asked for a refund" --explain
```
```txt
Included:
✓ mission canonical
✓ policies.refunds canonical
✓ procedures.refund approved
Excluded:
- decisions.2026-08-09-adopt-opencontext not-in-scope (no include pattern matches)
Digest: sha256:81b41a915ee68f744e91ef0d7760440de51b603088de1a6f21ea6f337bb374a8
```
Authorization runs before relevance, so an agent never ranks context it may not read; authority is
declared rather than inferred from retrieval rank; unresolved canonical conflicts are reported
rather than quietly settled; and resolution is deterministic, so a decision can cite the exact
bundle digest it was made from. Untrusted content — tickets, chats, scraped pages — keeps its trust
level through resolution and is fenced and labelled in rendered bundles.
It is not a memory database. Memory is one possible context source; OpenContext is the control
plane above systems that remain the sources of truth. It runs from a folder and a Git repository
with no account, no server, and no telemetry.
Also available as `logicsrc context <command>`, sharing one implementation with the standalone
binary. See the [specification](docs/opencontext/spec.md), [CLI](docs/opencontext/cli.md),
[SDK](docs/opencontext/sdk.md), [security model](docs/opencontext/security.md), and
[conformance guide](docs/opencontext/conformance.md).
## One command for every LogicSRC tool
`logicsrc` is the umbrella: every LogicSRC standard that has a CLI is a word after it, and the word runs the same code as the standalone command, so the two cannot drift.
```bash
logicsrc vault … # OpenCreds (also `opencreds`)
logicsrc prd … # OpenPRD
logicsrc ontology … # OpenOntology
logicsrc context … # OpenContext (also `opencontext`)
logicsrc fleet … # OpenFleet: open, cap, tree, stop, log, hooks install
logicsrc errand … # OpenErrand: run, validate, status (an errand on a site with no API, gates kept human)
logicsrc openmcp … # OpenMCP: relays, find, call, add, probe, serve (also `openmcp`)
logicsrc openspec … # import, export, change; any other word is OpenSpec.dev's own CLI (init, list, validate, archive, show)
logicsrc mcp # the LogicSRC MCP server over stdio (also `logicsrc-mcp`)
```
`openmcp` is the one that lives in its own repository ([logicsrc/openmcp](https://github.com/logicsrc/openmcp)); it is a dependency here and its `main` is called with your arguments untouched. It needs Node 24 (`node:sqlite`); on an older Node that one word says so and the rest of the CLI keeps working. The standalone install, which brings its own Node 24, is `curl -fsSL https://openmcp.logicsrc.com/install.sh | sh`.
## MCP
LogicSRC exposes a standards-focused MCP server as `@profullstack/logicsrc-mcp`, and `logicsrc mcp` runs it.
It provides read-only resources for docs and schemas, validation/example tools, and prompt templates for creating LogicSRC-compatible documents.
## v1.0.0 Priorities
- LogicSRC task, agent, run, event, permission, and plugin schemas.
- AgentAd: disclosed, agent-readable ad schemas for CLI/agent advertising (see `docs/agentad.md`); cl1s.tech is the reference network. The two-sided exchange on top is specified in `docs/agentad-marketplace.md`.
- LogicSRC CLI, SDK, TUI, PWA, MCP, and curl-compatible API conventions.
- CommandBoard.run reference implementation.
- Monorepo-maintained plugin system.
- Credential Sharing OpenSpec for end-to-end-encrypted team vaults, .env, Doppler, Railway variables, GitHub Secrets, sh1pt, and `~/.ssh` keys.
- CoinPay as the default payment, DID, wallet, and escrow plugin.
- uGig as the default jobs and gigs marketplace plugin.
- c0mpute as a work-in-progress compute jobs and worker pools plugin.
- Installer, update/upgrade, remove/uninstall workflows.
## OpenABTest draft
[OpenABTest](docs/openabtest.md) defines reusable experiment manifests and private
eligibility, assignment, exposure, conversion and accounting events. The Chovy
example compares 5%, 10% and 20% discounts on every referred purchase, with
sticky customer assignment and affiliate payout withheld until actual costs
and fees are reconciled. Schemas, validators and SDK constructors ship in 0.3.0;
assignment, analytics and payment runtimes remain the integrating service's job.
Reference in a new issue View git blame Copy permalink