@glyphs-ai/glyph 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lang Cheng
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,245 @@
+# Glyph
+
+[![npm version](https://img.shields.io/npm/v/@glyphs-ai/glyph.svg)](https://www.npmjs.com/package/@glyphs-ai/glyph)
+[![CI](https://github.com/glyphs-ai/glyph/actions/workflows/ci.yml/badge.svg)](https://github.com/glyphs-ai/glyph/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+
+A glyph is the visible form of an idea. In typography, the *character* is
+abstract; the *glyph* is how that character is rendered in a particular
+font, weight, and context. The character is the meaning; glyphs are the
+forms it takes.
+
+We believe intelligence works the same way. Intent, reasoning, memory,
+and collaboration are the abstractions. What we actually touch — models,
+prompts, agents, tools, workflows — are their current glyphs. Those
+forms will keep changing. The abstractions beneath them won't.
+
+Glyph the project is a workbench for exploring, composing, and evolving
+those forms, while staying independent of any particular implementation
+or era of AI. The future of intelligence is unlikely to be written in
+today's language — we're still learning its alphabet.
+
+> **Pre-1.0 — APIs may change.** Targeted at solo developers and small teams
+> running glyph against their own machine; multi-user deployment is not yet
+> a goal.
+
+## Quickstart
+
+```sh
+npm install -g @glyphs-ai/glyph
+glyph start
+```
+
+Then open <http://127.0.0.1:8787> in your browser. `glyph start` runs the
+server as a detached background process so the terminal is free; the rest
+of the lifecycle is `glyph stop`, `glyph restart`, `glyph status`,
+and `glyph logs -f`. Run `glyph help` (or just `glyph`) for the full
+command tree, or `glyph serve` to keep it in the foreground (the legacy
+behaviour, useful for `tmux` panes or `systemd` units).
+
+The first time you run `glyph`, the dashboard's landing page is empty.
+Walk through:
+
+1. **Add a workspace** — give it a display name. Optionally pick a directory
+   on disk; if you don't, glyph creates one under
+   `$GLYPH_HOME/workspaces/<uuid>/` so the workspace id and the on-disk
+   directory share the same name. Either way glyph writes
+   a `workspace.db` SQLite file plus `sessions/` and `tasks/` subdirs
+   inside; existing files in a user-supplied directory are left alone.
+2. **Install an agent** in the Catalog tab — point at any directory containing
+   an `AGENTS.md` (a [Claude-style agent](https://www.claude.com/news/agent-skills);
+   any directory with valid frontmatter works). Skills + MCPs the agent
+   depends on go in the same way.
+3. **Dispatch a task** in the Tasks tab — pick the agent, write a brief
+   (one-line goal) and optional details, click *Dispatch*. The agent runs
+   unattended in a new sandbox under
+   `tasks/<id>/`; the dashboard shows the live event stream and folds the
+   exit into a final `succeeded` / `failed` / `cancelled` status.
+4. **Or open a session** in the Sessions tab — interactive workdir; glyph
+   bakes the agent into it and gives you the exact `copilot` invocation to
+   run yourself.
+
+## Configuration
+
+All configuration is via environment variables; no config file. Defaults
+work for single-machine use; only set what you need to override.
+
+| Env var              | Default        | Purpose                                                                                                  |
+| -------------------- | -------------- | -------------------------------------------------------------------------------------------------------- |
+| `PORT`               | `8787`         | HTTP listen port.                                                                                        |
+| `GLYPH_HOST`       | `127.0.0.1`    | Bind address. glyph is **loopback-only** — non-loopback values are refused at startup. For remote access, expose the loopback socket through SSH port-forward, a reverse proxy (mTLS / OIDC), or a mesh VPN (Tailscale, …). |
+| `GLYPH_HOME`       | `~/.glyph`   | Where the global SQLite registry (`global.db`) lives.                                                  |
+| `GLYPH_LOG_LEVEL`  | `info`         | `debug` / `info` / `warn` / `error`.                                                                     |
+| `GLYPH_LOG_FORMAT` | `pretty`       | `pretty` (dev terminal) or `json` (log aggregators).                                                     |
+| `GLYPH_STATIC_DIR` | next to bundle | Override the dashboard SPA location. Useful when running from a non-bundle layout.                       |
+
+Pass `--no-serve-static` to run API-only (the dashboard SPA is bundled in
+the npm package by default; serving it from the same port is the only
+deployment mode that makes sense for the local-first model).
+
+## Filesystem contract
+
+Everything glyph writes under `<GLYPH_HOME>` (default `~/.glyph`)
+and per-workspace internals is **server-internal state**. The layout —
+file names, JSON shapes, SQLite schemas, sidecar files — is implementation
+detail and may change between versions. Reading these files for inspection
+is fine; **anything else (writes, hand-edits, `rm`) is unsupported and
+may be detected as corruption.**
+
+For the path-by-path layout (what glyph owns vs the agent vs the
+runtime adapter) and the rationale for keeping clients out of
+`<GLYPH_HOME>/`, see [`docs/architecture.md` →
+Filesystem contract](./docs/architecture.md#filesystem-contract).
+
+## CLI
+
+After `npm install -g @glyphs-ai/glyph` the `glyph` binary exposes
+two layers of commands:
+
+### Lifecycle (talk to the local process)
+
+| Command            | Behaviour                                                                                                                                                                |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `glyph`          | Print top-level help (alias for `glyph help`).                                                                                                                         |
+| `glyph help [c]` | Top-level help, or per-subcommand help when `c` is given.                                                                                                                |
+| `glyph serve`    | Run the server in the foreground — current dev behaviour. Honours every env var in the *Configuration* table; flags override env.                                        |
+| `glyph start`    | Spawn the server as a detached background process. Records pid + port in `<GLYPH_HOME>/runtime.json`. Idempotent.       |
+| `glyph stop`     | SIGTERM the recorded pid, wait for graceful shutdown (escalates to SIGKILL after 30 s), then delete `runtime.json`. Idempotent. *Windows note:* `process.kill` maps to `TerminateProcess` — there is no graceful equivalent on Windows; the server's atomic-write persistence keeps state consistent regardless. |
+| `glyph restart`  | `stop` then `start` with the same flags.                                                                                                                                 |
+| `glyph status`   | Print one-line health summary. Exit codes: `0` running + healthy, `3` not running, `4` running but `/api/health` not responding. `--json` for scripts.                   |
+| `glyph logs`     | Cat the rolling server log under `<GLYPH_HOME>/logs/`. `-f` follows the file as it grows (Ctrl-C to stop).                                                             |
+
+### API client (talk to a running server)
+
+65 typed routes — wrapped 1:1 by the CLI's `client.call(...)` surface;
+the typed manifest in `packages/contracts/src/routes.ts` is the single
+source of truth that both the server registers handlers against and
+the CLI builds typed calls from. Adding a route on either side
+without updating the other fails CI.
+
+```sh
+# server connection (default: http://127.0.0.1:8787, picked up from
+# `runtime.json` when `glyph start` has run)
+glyph health
+glyph config --json
+glyph runtime list
+
+# workspaces
+glyph workspace list
+glyph workspace add --name "Sandbox" --workdir ~/code/sandbox
+export GLYPH_WORKSPACE=<id>          # required for workspace-scoped commands
+glyph workspace show <id>
+glyph workspace rm <id> --purge
+
+# sessions and tasks (workspace-scoped; pass --workspace <id> to override the env above)
+glyph session new --agent writer
+glyph session list --agent writer --json
+glyph task dispatch --agent triage --brief "Scan recent issues"
+glyph task list --status running,succeeded
+glyph task events <tid>     # one-shot dump of the runtime's NDJSON log
+glyph task activity <tid>   # runtime-parsed activity timeline (JSON)
+
+# catalog
+glyph catalog overview
+glyph catalog skill list
+glyph catalog skill install --file /abs/path/to/skill
+glyph catalog agent install --url https://github.com/glyphs-ai/glyph/tree/main/first-party/agents/engineer
+glyph catalog mcp install --url https://github.com/glyphs-ai/glyph/tree/main/first-party/mcps/example.json
+```
+
+Common flags on every API command:
+
+- `--server <url>` — overrides `GLYPH_SERVER` and `runtime.json`. Defaults to `http://127.0.0.1:8787`.
+- `--workspace <id>` — workspace-scoped commands. Overrides `GLYPH_WORKSPACE` and the server's `currentWorkspace`.
+- `--output <fmt>` / `--json` — `table` (human-friendly default) or `json` (for scripting).
+
+Exit codes: `0` success, `1` generic error, `2` usage error, `3` server unreachable, `4` server returned a 4xx/5xx.
+
+## Where this sits
+
+Glyph does not invent a new agent format — it adopts the
+[MetaAgents](https://github.com/metaagents-ai/metaagents) Layer-0 spec where
+agents are markdown files (`AGENTS.md`) with YAML frontmatter, skills are
+markdown files (`SKILL.md`) with YAML frontmatter, and MCPs are JSON config
+blobs. What glyph adds:
+
+- **A dependency-aware catalog** — agents declare which skills + MCPs they
+  need; glyph topologically resolves them, blocks cycles, and refuses to
+  uninstall something another entry depends on.
+- **A workspace abstraction** — multiple isolated projects on one machine;
+  each picks its own agent set without polluting the others.
+- **Runtime adapters** — first-class support for the
+  [GitHub Copilot CLI](https://github.com/github/gh-copilot) today; the same
+  surface lets future runtimes (Gemini, Claude Code, …) drop in.
+- **Three execution modes** — interactive `session`, one-shot `task`, and
+  multi-task `workflow` (a DAG of sessions and tasks coordinated by a
+  long-running coordinator agent). All three persist across server
+  restarts and share a structured `running → succeeded/failed/cancelled`
+  lifecycle.
+
+## Architecture
+
+The repo is a [pnpm](https://pnpm.io/workspaces) monorepo of 14 small
+TypeScript packages with a strict layering: pure value types at the bottom,
+file-system primitives next, entity managers above (workspace / catalog /
+session / task / workflow), then the runtime adapter, then the HTTP server,
+then the React dashboard. See [`docs/architecture.md`](./docs/architecture.md)
+for the design contract — repository pattern, atomic-write seam, REST URL
+scheme, and the rationale behind the package boundaries.
+
+The conceptual model — how we think about agentic systems and why
+glyph is shaped the way it is — lives in the **paper
+[*What we believe about agentic systems*](https://glyphs-ai.github.io/glyph/)**.
+It's a short read; if its premises resonate with you, the rest of the
+codebase will make sense more quickly.
+
+Each package's own README documents its public API surface; the most
+important ones for downstream consumers are
+[`@glyphs-ai/catalog`](./packages/catalog),
+[`@glyphs-ai/workspace`](./packages/workspace),
+[`@glyphs-ai/task`](./packages/task),
+[`@glyphs-ai/session`](./packages/session),
+[`@glyphs-ai/workflow`](./packages/workflow),
+[`@glyphs-ai/runtime`](./packages/runtime), and
+[`@glyphs-ai/server`](./packages/server).
+
+## First-party catalog
+
+The repo ships a [`first-party/`](./first-party/) subtree of agents and
+skills (scope `official`) that the project maintains in lock-step with the
+code — they depend on internals (catalog schema, CLI surface) tightly
+enough to version-bump and PR together with the packages that define
+those internals. See [`first-party/README.md`](./first-party/README.md)
+for the full list and install URLs. Third-party catalogs can be installed
+the same way as first-party entries (any reachable GitHub URL).
+
+## Development
+
+Requires Node ≥ 22, pnpm ≥ 10.
+
+```sh
+git clone https://github.com/glyphs-ai/glyph.git
+cd glyph
+pnpm install
+pnpm build       # tsc emit (run first; downstream packages import upstream .d.ts)
+pnpm typecheck   # tsc --noEmit across all packages
+pnpm test        # vitest across all packages
+pnpm lint        # biome check
+```
+
+Run the dev server (hot-reloading API + Vite-served dashboard):
+
+```sh
+pnpm dev
+# API on http://127.0.0.1:8787
+# Dashboard dev server on http://127.0.0.1:41817 (proxies /api → 8787)
+```
+
+For everything beyond the basics — repository pattern, atomic-write
+guarantees, how to add a new runtime adapter — see
+[`docs/architecture.md`](./docs/architecture.md). Release procedure
+lives in [`docs/RELEASING.md`](./docs/RELEASING.md).
+
+## License
+
+MIT — see [LICENSE](./LICENSE).