artemys 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+## Unreleased
+
+## 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,234 +1,282 @@
 <div align="center">
 
-<img src="https://raw.githubusercontent.com/artemyshq/artemys/main/.github/assets/artie-icon.svg" width="52" alt="Artie">
+<img src="https://gist.githubusercontent.com/jblue-ops/4f2ddf27e37b2ca8358168535c8fd8ee/raw/artemys-icon.svg" width="56" alt="Artemys">
 
-<h1>A R T E M Y S</h1>
+# Artemys
 
-**The open ecosystem for agent-to-agent career communication**
-
-*Athletes have agents. Executives have agents. Actors have agents.<br>
-Now everyone does.*
-
-<br>
+**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/)
-[![tests](https://img.shields.io/badge/tests-155%2B_passing-000?style=flat-square)](https://github.com/artemyshq/artemys)
+[![TypeScript](https://img.shields.io/badge/TypeScript-000?style=flat-square&logo=typescript&logoColor=fff)](https://www.typescriptlang.org/)
 
-**[Vision](docs/VISION.md)** · **[Docs](docs/)** · **[Protocol Spec](protocol/)** · **[npm](https://www.npmjs.com/package/artemys)**
+[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>
 
----
-
-## The Problem
+<br>
 
-Every hiring system in the market was built for the old world. And every communication channel between talent and opportunity was built for a world where humans do the talking.
+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.
 
-**The systems are broken.** They assume stable job families, linear career paths, and credentials as efficient proxies for capability. They filter people based on keywords, titles, and years — the exact signals that are losing meaning. 98% of Fortune 500 companies use AI in hiring — to automate the same broken credential-matching faster.
+This package provides the interoperability primitives: protocol schemas, authenticated transport, discovery, and an MCP bridge. Runtime and product logic belong downstream.
 
-**The communication is broken.** Candidates manually update profiles, write performative cover letters, and spray-and-pray applications. Recruiters send mass outreach that gets ignored. Both sides spend 90% of their time on overhead and 10% on signal. LinkedIn has become a spam wasteland where everyone performs and nobody communicates.
+Start with `docs/FUNDAMENTALS.md` for the implementation map (plug in -> meet -> converse).
 
-**The result:** The recruiter who ships production software gets filtered out because they're "not an engineer on paper." Career changers, non-traditional builders, and high-agency generalists are structurally invisible. And even when the right person and the right opportunity exist in the same market, the communication infrastructure between them is so noisy and broken that they never connect.
+<br>
 
-The industry is racing to automate the existing process faster. Nobody is asking whether the process itself is wrong.
+## Architecture
 
----
+```
+                        ┌──────────────────────────────────┐
+                        │          Coffee Shop             │
+                        │    (discovery + introductions)    │
+                        └──────┬───────────────┬───────────┘
+                               │               │
+                          discover          introduce
+                               │               │
+               ┌───────────────┴───┐       ┌───┴───────────────┐
+               │   Candidate Agent │       │    Talent Agent    │
+               │                   │       │                    │
+               │  ┌─────────────┐  │       │  ┌─────────────┐  │
+               │  │  Protocol   │◄─┼───────┼──►  Protocol   │  │
+               │  │  Schemas    │  │ HMAC   │  │  Schemas    │  │
+               │  └─────────────┘  │ HTTP   │  └─────────────┘  │
+               └───────────────────┘       └───────────────────┘
+```
 
-## You Deserve Representation
+<br>
 
-Athletes have agents. Executives have agents. Actors have agents.
+## Install
 
-These agents exist because **talent shouldn't have to sell itself**. An agent knows the market, understands your worth, handles the noise, and makes sure you only spend time on opportunities that matter. They represent your interests — not the buyer's.
+```bash
+npm install artemys
+```
 
-Why doesn't everyone have this?
+<br>
 
-Because until now, it didn't scale. A human agent for every professional in the world isn't possible. **But an AI agent is.** One that knows your skills, understands your goals, respects your boundaries, and works on your behalf around the clock.
+## Modules
 
-**That's what Artemys makes possible.**
+| 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) |
 
-Artemys is the open ecosystem for building career agents — the protocol they speak, the schemas they validate against, the runtime they run on, and the discovery layer where they find each other. Anyone can build a candidate agent or a talent agent on top of it.
+<br>
 
-> **The candidate sets direction and boundaries. Their agent handles everything else.**
+## Quick Start
 
-We're building **[Artie](https://artemys.ai)** — a candidate agent powered by Artemys. But the ecosystem is open: anyone can build agents that speak the protocol.
+Reference runnable examples: `examples/README.md`
 
----
+### Validate a protocol message
 
-## How It Works
+```typescript
+import { ProtocolMessageSchema, HandshakeInitiateSchema } from "artemys"
 
+const result = ProtocolMessageSchema.safeParse(incomingMessage)
+if (!result.success) {
+  console.error(result.error.issues)
+}
 ```
-      You                                         Company
-       │                                              │
-  ┌────▼──────┐    ◆ Artemys Protocol ◆    ┌──────────▼──┐
-  │ Your Agent │◄──────────────────────────►│ Talent Agent │
-  │(e.g. Artie)│  discover → handshake →   │   (Theirs)   │
-  └────────────┘  consent → dialogue →     └──────────────┘
-                  resolution
+
+### Send a signed message
+
+```typescript
+import { ProtocolTransportClient } from "artemys/transport"
+
+const transport = new ProtocolTransportClient({
+  agentId: "candidate-agent-01",
+  getSharedSecret: async (peerId) => secrets.get(peerId),
+})
+
+const result = await transport.send(
+  "https://peer.example.com/artemys/v0.1/messages",
+  message
+)
 ```
 
-When both sides have agents, professional career communication transforms:
+### Discover agents via Coffee Shop
 
-| Today (Human-to-Human) | Artemys (Agent-to-Agent) |
-|-------------------------|--------------------------|
-| Recruiter sends cold email | Talent agent queries candidate Arties matching real criteria |
-| Candidate ignores 95% of messages | Artie evaluates and silently declines irrelevant queries |
-| Candidate manually tailors resume per app | Artie shares relevant evidence contextually |
-| Both sides guess at fit through phone screens | Agents exchange structured information progressively |
-| Humans spend weeks on discovery | Agents resolve fit in hours; humans meet when it matters |
-| Ghosting, black holes, no feedback | Every interaction resolves: mutual interest, decline, or defer |
+Coffee Shop is the network receptionist for agents:
 
-**Consent is structural.** Candidates control what's shared, when, and with whom — enforced at the protocol level, not as a setting buried in a menu. The protocol ensures both sides progressively reveal information as trust builds. Neither side dumps everything upfront.
+- 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.
 
-## What We're Building
+```typescript
+import { CoffeeShopClient } from "artemys/coffeeshop"
 
-| We ARE Building | We Are NOT Building |
-|-----------------|---------------------|
-| Agent-to-agent career communication protocol | A LinkedIn replacement or job board |
-| Personal career agents that represent candidates 24/7 | A passive profile platform |
-| Autonomous talent agents that DO the job | AI tools that help humans do jobs faster |
-| Skills-based, agency-aware screening | Faster credential matching |
-| Open protocol anyone can build on | A walled garden |
-| Consent-native communication | Opt-out-only spam |
+const shop = new CoffeeShopClient({
+  baseUrl: "https://coffeeshop.artemys.ai",
+  apiKey: process.env.ARTEMYS_API_KEY,
+  agentId: "candidate-agent-01",
+})
 
----
+const agents = await shop.discover({
+  requester_agent_id: "candidate-agent-01",
+  role: "talent_agent",
+  limit: 20,
+})
+```
 
-## Install
+### Run the reference runtime loop
 
 ```bash
-npm install artemys
-# or
-bun add artemys
+bun run examples/reference-runtime-loop.ts
 ```
 
-## Quick Example
+```bash
+bun run examples/reference-runtime-loop.ts timeout
+```
 
-```typescript
-import { HandshakeInitiateSchema, PROTOCOL_VERSION } from "artemys"
-import { AgentCardSchema } from "artemys/discovery"
-import { ArtemysRuntime, loadConfig } from "artemys/agent"
-
-// Every agent starts with a card — who you are, what you can do
-const card = AgentCardSchema.parse({
-  agent_id: "artie-001",
-  display_name: "Artie",
-  role: "candidate_agent",
-  protocol_versions: [PROTOCOL_VERSION],
-  capabilities: ["skills_exchange", "interview_prep"],
-  // ... endpoints, policy, attestation
-})
+### Run the MCP server
 
-// Start the runtime — your agent goes live
-const runtime = new ArtemysRuntime(loadConfig())
-await runtime.start()
+```bash
+artemys mcp-server --agent-card ./agent-card.json
 ```
 
----
+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.
 
-## Architecture
+<br>
+
+## Protocol
+
+The protocol defines how two agents conduct a structured career conversation, from first contact to resolution.
 
 ```
-artemys
-├── 📋 Protocol      Zod schemas · state machine · message validation
-├── ☕ Discovery      Agent cards · registration · intro ("Coffee Shop")
-├── 🤖 Agent         Runtime · tools · scheduling · MCP integration
-├── 📡 Channels      Telegram adapter · channel registry
-└── ⚡ CLI           onboard · doctor · start
+NEW ──► HANDSHAKE_INITIATED ──► DIALOGUE_ACTIVE ──► RESOLVED
+                │                      │
+                ▼                      ▼
+        CANDIDATE_DECLINE    PAUSED_HUMAN_APPROVAL
 ```
 
-## Modules
+**12 message types** across 4 phases — handshake, dialogue, consent, resolution — with sender role constraints, schema validation, and deterministic state transitions.
 
-### 📋 Protocol
+The protocol spec is frozen at **v0.1.0** with 41 contract fixtures and conformance tests.
 
-Typed Zod schemas for the full conversation lifecycle — handshake, consent gates, dialogue, and resolution.
+**[Read the full spec &rarr;](protocol/)**
 
-```typescript
-import { HandshakeInitiateSchema, PROTOCOL_VERSION } from "artemys"
-// or explicitly:
-import { HandshakeInitiateSchema } from "artemys/protocol"
-```
-
-Includes `Envelope`, `ConversationState`, state machine transitions, `ConsentProfile`, `ConsentGate`, `FitAssessment`, and 20+ message schemas covering every phase of agent-to-agent communication.
+<br>
 
-### ☕ Discovery
+## Transport
 
-The "Coffee Shop" layer — where agents find each other, exchange cards, and bootstrap sessions.
+Messages travel over HTTPS with HMAC-SHA256 authentication:
 
-```typescript
-import { AgentCardSchema, DiscoveryQuerySchema } from "artemys/discovery"
-```
+- **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)
 
-Includes `AgentCard`, `DiscoveryQuery`, `IntroRequest`, `SessionBootstrap`, and relay/direct handoff flows.
+**[Transport spec &rarr;](protocol/docs/TRANSPORT_HTTP.md)**
 
-### 🤖 Agent
+<br>
 
-Runtime framework for building career agents with built-in tools, task scheduling, browser automation, and MCP integration.
+## CLI
 
-```typescript
-import { ArtemysRuntime, loadConfig } from "artemys/agent"
+```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
 ```
 
-**Built-in tools:** career advice · resume generation · market data · job search · web search · browser automation · memory · shell · task scheduling
-
-### 📡 Channels
+<br>
 
-Communication adapters for reaching agents wherever they are.
+## Project Structure
 
-```typescript
-import { TelegramAdapter } from "artemys/channels/telegram"
-import { ChannelRegistry } from "artemys/channels"
 ```
+src/
+  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>
 
-### ⚡ CLI
+## Development
 
 ```bash
-artemys onboard   # Guided agent setup
-artemys doctor    # Validate your configuration
-artemys start     # Launch your agent
+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
 ```
 
----
+### Coffee Shop Service (Turso/libSQL)
 
-## Ecosystem
+```bash
+cd service
+bun install
 
-| | Component | Role |
-|---|-----------|------|
-| 🔷 | **[artemys](https://github.com/artemyshq/artemys)** | Open ecosystem + SDK *(you are here)* |
-| 🟢 | **[Artie](https://artemys.ai)** | Reference candidate agent — your personal career agent |
-| 🟠 | **Talent Agents** | Employer-side agents — anyone can build one using the protocol |
+# Use durable DB mode
+export ARTEMYS_DB_DRIVER=libsql
+export TURSO_DATABASE_URL="libsql://..."
+export TURSO_AUTH_TOKEN="..."
 
-The protocol is open. The SDK is open. Build your own agent, extend the protocol, or use Artie out of the box.
+# Run schema migrations once per environment
+bun run migrate
 
----
+# Run service tests/type-check
+bun run type-check
+bun run test
 
-## Development
+# 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
-bun install              # Install dependencies
-bun run build            # Build the SDK
-bun run test             # Run 155+ tests
-bun run type-check       # TypeScript validation
-bun run protocol:check   # Protocol conformance tests
+export ARTEMYS_ALLOW_IN_MEMORY_DB=true
 ```
 
-## Docs
+Metrics endpoint auth:
 
-| | Document | Covers |
-|---|---------|--------|
-| 📖 | **[Vision](docs/VISION.md)** | Why we exist · What we believe · What we're building |
-| 💡 | **[Why Artie](docs/WHY-ARTIE.md)** | The candidate story · What's broken · What Artie fixes |
-| 🔧 | **[How Artie Works](docs/HOW-ARTIE-WORKS.md)** | Product and technical reference |
-| 📋 | **[Protocol Spec](protocol/)** | Normative docs · Fixtures · Conformance checklist |
+- 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"
+```
 
-<div align="center">
+Attestation policy defaults to enforce. Explicit local opt-out:
 
-**Built for a world where talent has representation.**
+```bash
+export ARTEMYS_ATTESTATION_MODE=warn
+```
+
+<br>
+
+## Contributing
 
-[MIT License](LICENSE)
+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

@@ -1,3 +1,3 @@
 #!/usr/bin/env node
-export {};
+export declare function runCli(argv?: string[]): Promise<void>;
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":""}
+{"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"}