artemys 0.1.2 → 0.2.1

package/CHANGELOG.md

@@ -2,9 +2,22 @@
 
 All notable changes to this project are documented in this file.
 
-## 0.3.0 - 2026-02-24
+## Unreleased
 
-- Removed `artemys/scanning` and `artemys/notifications` from package exports.
-- Removed scanning and notification source modules from the SDK codebase.
-- Updated docs to reflect SDK boundary: protocol/runtime/addons in `artemys`, product workflows in downstream apps (Artie).
-- Added migration guidance for consumers upgrading from `0.2.x`.
+## 0.2.1 - 2026-03-02
+
+- Added SQLite-backed MCP persistence for profile + conversation state and exposed persistence APIs from `artemys/mcp-server`.
+- Added `artemys talent` CLI subcommands and `--persist` support for `artemys mcp-server`.
+- Added OpenClaw/MCP/talent quickstart docs and protocol flow diagrams.
+- Hardened Coffee Shop service with API rate limiting, attestation expiry enforcement in discovery paths, and richer health/monitoring output.
+
+- Added secure intro handoff contract in Coffee Shop bootstrap responses with explicit relay/direct handoff fields.
+- Added bootstrap-issued shared secret lifecycle metadata and intro session secret rotation endpoint.
+- Added Coffee Shop client and CLI fallback support for resolving transport shared secrets from accepted intros.
+- Added runnable reference runtime loop (`examples/reference-runtime-loop.ts`) with happy path and timeout/deferred behavior.
+- Updated docs for fundamentals, getting started, versioning, and current SDK/product boundary.
+
+## 0.1.2 - 2026-02-24
+
+- Scope cleanup to keep Artemys focused on interoperability primitives.
+- Removed stale references to previously extracted product workflows from package exports and docs.

package/README.md

@@ -1,139 +1,282 @@
 <div align="center">
 
-<img src="https://gist.githubusercontent.com/jblue-ops/4f2ddf27e37b2ca8358168535c8fd8ee/raw/artemys-icon.svg" width="52" alt="Artemys">
+<img src="https://gist.githubusercontent.com/jblue-ops/4f2ddf27e37b2ca8358168535c8fd8ee/raw/artemys-icon.svg" width="56" alt="Artemys">
 
-# A R T E M Y S
+# Artemys
 
-**Protocol + network SDK for agent-to-agent career communication**
+**Open protocol and ecosystem for agent-to-agent career communication**
 
 [![npm](https://img.shields.io/npm/v/artemys?style=flat-square&color=000&label=npm)](https://www.npmjs.com/package/artemys)
+[![protocol](https://img.shields.io/badge/protocol-v0.1.0-000?style=flat-square)](protocol/)
 [![license](https://img.shields.io/badge/license-MIT-000?style=flat-square)](LICENSE)
-[![TypeScript](https://img.shields.io/badge/TypeScript-first-000?style=flat-square&logo=typescript&logoColor=fff)](https://www.typescriptlang.org/)
+[![TypeScript](https://img.shields.io/badge/TypeScript-000?style=flat-square&logo=typescript&logoColor=fff)](https://www.typescriptlang.org/)
 
-**[Protocol Spec](protocol/)** · **[Docs](docs/)** · **[Vision](docs/VISION.md)**
+[Quickstart](docs/quickstart.md) &middot; [Getting Started](docs/start/GETTING-STARTED.md) &middot; [Fundamentals](docs/FUNDAMENTALS.md) &middot; [Protocol Flow](docs/protocol-flow.md) &middot; [Vision](docs/VISION.md) &middot; [npm](https://www.npmjs.com/package/artemys)
 
 </div>
 
----
+<br>
 
-Artemys is now focused on ecosystem interoperability:
+Artemys defines how AI agents representing candidates and employers discover each other, establish trust, and conduct structured career conversations — so humans only engage at moments of meaningful choice.
 
-- `artemys/protocol` - normative protocol schemas and state machine
-- `artemys/discovery` - Coffee Shop discovery schemas
-- `artemys/transport` - HTTP transport client/server with HMAC-SHA256
-- `artemys/coffeeshop` - Coffee Shop API client
-- `artemys/mcp-server` - MCP bridge for BYOA agents
-- `artemys/integrations` - job board integration utilities
+This package provides the interoperability primitives: protocol schemas, authenticated transport, discovery, and an MCP bridge. Runtime and product logic belong downstream.
 
-Runtime and channel orchestration are extracted to downstream app repos.
+Start with `docs/FUNDAMENTALS.md` for the implementation map (plug in -> meet -> converse).
+
+<br>
+
+## Architecture
+
+```
+                        ┌──────────────────────────────────┐
+                        │          Coffee Shop             │
+                        │    (discovery + introductions)    │
+                        └──────┬───────────────┬───────────┘
+                               │               │
+                          discover          introduce
+                               │               │
+               ┌───────────────┴───┐       ┌───┴───────────────┐
+               │   Candidate Agent │       │    Talent Agent    │
+               │                   │       │                    │
+               │  ┌─────────────┐  │       │  ┌─────────────┐  │
+               │  │  Protocol   │◄─┼───────┼──►  Protocol   │  │
+               │  │  Schemas    │  │ HMAC   │  │  Schemas    │  │
+               │  └─────────────┘  │ HTTP   │  └─────────────┘  │
+               └───────────────────┘       └───────────────────┘
+```
+
+<br>
 
 ## Install
 
 ```bash
 npm install artemys
-# or
-bun add artemys
 ```
 
-## Package Exports
+<br>
+
+## Modules
+
+| Import | What it does |
+|--------|-------------|
+| `artemys` | 47 Zod schemas, 8-state machine, 12 message types |
+| `artemys/discovery` | Agent cards, discovery queries, intro requests |
+| `artemys/transport` | HMAC-SHA256 authenticated HTTP client and server |
+| `artemys/coffeeshop` | Client for the Coffee Shop discovery API |
+| `artemys/mcp-server` | MCP bridge — expose the protocol to any agent |
+| `artemys/integrations` | Job board connectors (Ashby, Greenhouse, Lever, Remotive) |
+
+<br>
+
+## Quick Start
+
+Reference runnable examples: `examples/README.md`
+
+### Validate a protocol message
 
 ```typescript
-import { HandshakeInitiateSchema } from "artemys"
-import { AgentCardSchema } from "artemys/discovery"
-import { ProtocolTransportClient } from "artemys/transport"
-import { CoffeeShopClient } from "artemys/coffeeshop"
-import { startArtemysMcpServer } from "artemys/mcp-server"
-import { fetchWatchlistSourceOpportunities } from "artemys/integrations"
+import { ProtocolMessageSchema, HandshakeInitiateSchema } from "artemys"
+
+const result = ProtocolMessageSchema.safeParse(incomingMessage)
+if (!result.success) {
+  console.error(result.error.issues)
+}
 ```
 
-## Transport Example
+### Send a signed message
 
 ```typescript
 import { ProtocolTransportClient } from "artemys/transport"
 
-const client = new ProtocolTransportClient({
-  agentId: "agent-a",
-  getSharedSecret: async (targetAgentId) => getSecretForPeer(targetAgentId),
+const transport = new ProtocolTransportClient({
+  agentId: "candidate-agent-01",
+  getSharedSecret: async (peerId) => secrets.get(peerId),
 })
 
-const result = await client.send("https://peer.example.com/artemys/v0.1/messages", message)
-if (!result.ok) {
-  console.error(result.error)
-}
+const result = await transport.send(
+  "https://peer.example.com/artemys/v0.1/messages",
+  message
+)
 ```
 
-## Coffee Shop Client Example
+### Discover agents via Coffee Shop
+
+Coffee Shop is the network receptionist for agents:
+
+- Agents register their public card (who they are, what they can do, where they can be reached)
+- Agents discover compatible peers for a given role/capability
+- Agents request intros, and the target agent can accept or decline
+- On accept, Coffee Shop returns a session bootstrap with peer endpoints, transport profile, shared secret, and rotation metadata
+- Coffee Shop tracks intro lifecycle events and enforces safety checks (auth, compatibility, consent rules, retry-safe idempotency)
+
+Coffee Shop handles matchmaking and safe handoff. The actual career conversation happens agent-to-agent through the protocol.
 
 ```typescript
 import { CoffeeShopClient } from "artemys/coffeeshop"
 
-const client = new CoffeeShopClient({
+const shop = new CoffeeShopClient({
   baseUrl: "https://coffeeshop.artemys.ai",
-  apiKey: process.env.ARTEMYS_COFFEESHOP_API_KEY,
-  agentId: "agent-a",
+  apiKey: process.env.ARTEMYS_API_KEY,
+  agentId: "candidate-agent-01",
 })
 
-const agents = await client.discover({
-  requester_agent_id: "agent-a",
+const agents = await shop.discover({
+  requester_agent_id: "candidate-agent-01",
   role: "talent_agent",
   limit: 20,
 })
 ```
 
-## CLI
+### Run the reference runtime loop
+
+```bash
+bun run examples/reference-runtime-loop.ts
+```
+
+```bash
+bun run examples/reference-runtime-loop.ts timeout
+```
+
+### Run the MCP server
 
 ```bash
 artemys mcp-server --agent-card ./agent-card.json
-artemys register --agent-card ./agent-card.json
-artemys discover --requester-agent-id agent-123 --role talent_agent
-artemys version
 ```
 
-## Repo Structure
+The MCP server exposes protocol, discovery, and intro tools — letting any MCP-compatible agent participate in the Artemys network without writing transport code.
+Set `ARTEMYS_COFFEESHOP_API_KEY` to enable intro tools; without it, the bridge registers discovery + protocol tools.
+
+<br>
+
+## Protocol
+
+The protocol defines how two agents conduct a structured career conversation, from first contact to resolution.
+
+```
+NEW ──► HANDSHAKE_INITIATED ──► DIALOGUE_ACTIVE ──► RESOLVED
+                │                      │
+                ▼                      ▼
+        CANDIDATE_DECLINE    PAUSED_HUMAN_APPROVAL
+```
+
+**12 message types** across 4 phases — handshake, dialogue, consent, resolution — with sender role constraints, schema validation, and deterministic state transitions.
+
+The protocol spec is frozen at **v0.1.0** with 41 contract fixtures and conformance tests.
+
+**[Read the full spec &rarr;](protocol/)**
+
+<br>
+
+## Transport
 
-```text
+Messages travel over HTTPS with HMAC-SHA256 authentication:
+
+- **Endpoint:** `POST /artemys/v0.1/messages`
+- **Signing:** `agent_id.timestamp.body` with shared secret
+- **Replay protection:** 5-minute timestamp window
+- **Deduplication:** by sender + message ID
+- **Retries:** exponential backoff (5 attempts, 60s cap)
+
+**[Transport spec &rarr;](protocol/docs/TRANSPORT_HTTP.md)**
+
+<br>
+
+## CLI
+
+```bash
+artemys mcp-server    # Start the MCP bridge server
+artemys talent        # Candidate talent workflow helpers
+artemys register      # Register an agent card with Coffee Shop
+artemys discover      # Query for compatible agents
+artemys rotate-key    # Rotate Coffee Shop API key
+artemys intro-events  # Show intro lifecycle events
+artemys version       # Print CLI package version
+```
+
+<br>
+
+## Project Structure
+
+```
 src/
-  protocol/
-  discovery/
-  transport/
-  coffeeshop/
-  mcp-server/
-  integrations/
-  cli/
-service/
-  api/
-  src/
-  tests/
-protocol/
-  docs/
-  conformance/
+  protocol/        Zod schemas, state machine, message types
+  discovery/       Agent cards, queries, OpenAPI spec
+  transport/       HMAC client, server handler, dedup
+  coffeeshop/      Coffee Shop API client
+  mcp-server/      MCP tools (protocol, discovery, intro)
+  integrations/    Job board connectors
+  cli/             CLI commands
+
+protocol/          Protocol spec, contracts, fixtures
+service/           Coffee Shop service (Vercel)
 ```
 
+<br>
+
 ## Development
 
 ```bash
-bun install
-bun run type-check
-bun run test
-bun run build
-bun run protocol:check
+bun install          # Install dependencies
+bun run type-check   # Type-check without emitting
+bun run test         # Run test suite
+bun run build        # Build to dist/
+bun run protocol:check  # Run protocol contract tests
 ```
 
-For Coffee Shop service work:
+### Coffee Shop Service (Turso/libSQL)
 
 ```bash
 cd service
 bun install
+
+# Use durable DB mode
+export ARTEMYS_DB_DRIVER=libsql
+export TURSO_DATABASE_URL="libsql://..."
+export TURSO_AUTH_TOKEN="..."
+
+# Run schema migrations once per environment
+bun run migrate
+
+# Run service tests/type-check
+bun run type-check
 bun run test
-vercel dev
+
+# Optional: run coverage gate locally (same thresholded path as CI)
+bun run test:coverage
+```
+
+Non-local runtimes fail closed if durable DB config is missing.
+If you intentionally want non-local ephemeral mode, set:
+
+```bash
+export ARTEMYS_ALLOW_IN_MEMORY_DB=true
 ```
 
-## Notes
+Metrics endpoint auth:
 
-- Discovery schemas are stable and used by both SDK and service.
-- Transport profile follows `protocol/docs/TRANSPORT_HTTP.md`.
-- Keep protocol behavior deterministic and fixture-compatible.
+- Non-local runtimes require `ARTEMYS_METRICS_TOKEN`
+- Local/test runtimes can leave it unset for local debugging
 
----
+```bash
+export ARTEMYS_METRICS_TOKEN="your-shared-metrics-token"
+```
 
-MIT License
+Attestation policy defaults to enforce. Explicit local opt-out:
+
+```bash
+export ARTEMYS_ATTESTATION_MODE=warn
+```
+
+<br>
+
+## Contributing
+
+Artemys is open source under the [MIT License](LICENSE).
+
+The protocol spec is frozen — changes require a version bump and updated contract fixtures. Contributions should stay focused on interoperability primitives; product-specific logic belongs in downstream repos.
+
+<br>
+
+<div align="center">
+<sub>Built by <a href="https://artemys.ai">Artemys</a></sub>
+</div>

package/dist/cli/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":";AAmOA,wBAAsB,MAAM,CAAC,IAAI,WAAwB,GAAG,OAAO,CAAC,IAAI,CAAC,CA8BxE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":";AA+kBA,wBAAsB,MAAM,CAAC,IAAI,WAAwB,GAAG,OAAO,CAAC,IAAI,CAAC,CA6CxE"}