fengming 0.3.9 → 0.3.11

package/docs/reference/credits.md

@@ -1,33 +0,0 @@
----
-summary: "Project origin, contributors, and license."
-read_when:
-  - You want the project backstory or contributor credits
-title: "Credits"
----
-
-## The name
-
-FengMing = CLAW + TARDIS, because every space lobster needs a time and space machine.
-
-## Credits
-
-- **Peter Steinberger** ([@steipete](https://x.com/steipete)) - Creator, lobster whisperer
-- **Mario Zechner** ([@badlogicc](https://x.com/badlogicgames)) - Pi creator, security pen tester
-- **Clawd** - The space lobster who demanded a better name
-
-## Core contributors
-
-- **Maxim Vovshin** (@Hyaxia, [36747317+Hyaxia@users.noreply.github.com](mailto:36747317+Hyaxia@users.noreply.github.com)) - Blogwatcher skill
-- **Nacho Iacovino** (@nachoiacovino, [nacho.iacovino@gmail.com](mailto:nacho.iacovino@gmail.com)) - Location parsing (Telegram and WhatsApp)
-- **Vincent Koc** ([@vincentkoc](https://github.com/vincentkoc), [@vincent_koc](https://x.com/vincent_koc)) - Agents, Telemetry, Hooks, Security
-
-## License
-
-MIT - Free as a lobster in the ocean.
-
-> "We are all just playing with our own prompts." (An AI, probably high on tokens)
-
-## Related
-
-- [Token use and costs](/reference/token-use)
-- [Release policy](/reference/RELEASING)

package/docs/reference/device-models.md

@@ -1,50 +0,0 @@
----
-summary: "How FengMing vendors Apple device model identifiers for friendly names in the macOS app."
-read_when:
-  - Updating device model identifier mappings or NOTICE/license files
-  - Changing how Instances UI displays device names
-title: "Device model database"
----
-
-The macOS companion app shows friendly Apple device model names in the **Instances** UI by mapping Apple model identifiers (e.g. `iPad16,6`, `Mac16,6`) to human-readable names.
-
-The mapping is vendored as JSON under:
-
-- `apps/macos/Sources/FengMing/Resources/DeviceModels/`
-
-## Data source
-
-We currently vendor the mapping from the MIT-licensed repository:
-
-- `kyle-seongwoo-jun/apple-device-identifiers`
-
-To keep builds deterministic, the JSON files are pinned to specific upstream commits (recorded in `apps/macos/Sources/FengMing/Resources/DeviceModels/NOTICE.md`).
-
-## Updating the database
-
-1. Pick the upstream commits you want to pin to (one for iOS, one for macOS).
-2. Update the commit hashes in `apps/macos/Sources/FengMing/Resources/DeviceModels/NOTICE.md`.
-3. Re-download the JSON files, pinned to those commits:
-
-```bash
-IOS_COMMIT="<commit sha for ios-device-identifiers.json>"
-MAC_COMMIT="<commit sha for mac-device-identifiers.json>"
-
-curl -fsSL "https://raw.githubusercontent.com/kyle-seongwoo-jun/apple-device-identifiers/${IOS_COMMIT}/ios-device-identifiers.json" \
-  -o apps/macos/Sources/FengMing/Resources/DeviceModels/ios-device-identifiers.json
-
-curl -fsSL "https://raw.githubusercontent.com/kyle-seongwoo-jun/apple-device-identifiers/${MAC_COMMIT}/mac-device-identifiers.json" \
-  -o apps/macos/Sources/FengMing/Resources/DeviceModels/mac-device-identifiers.json
-```
-
-4. Ensure `apps/macos/Sources/FengMing/Resources/DeviceModels/LICENSE.apple-device-identifiers.txt` still matches upstream (replace it if the upstream license changes).
-5. Verify the macOS app builds cleanly (no warnings):
-
-```bash
-swift build --package-path apps/macos
-```
-
-## Related
-
-- [Nodes](/nodes)
-- [Node troubleshooting](/nodes/troubleshooting)

package/docs/reference/fengming-sdk-api-design.md

@@ -1,390 +0,0 @@
----
-summary: "Reference design for the public FengMing App SDK API, event taxonomy, artifacts, approvals, and package structure"
-title: "FengMing App SDK API design"
-sidebarTitle: "App SDK API design"
-read_when:
-  - You are implementing the proposed public FengMing app SDK
-  - You need the draft namespace, event, result, artifact, approval, or security contract for the app SDK
-  - You are comparing Gateway protocol resources with the high-level FengMing App SDK wrapper
----
-
-This page is the detailed API reference design for the public
-[FengMing App SDK](/concepts/fengming-sdk). It is intentionally separate from
-the [Plugin SDK](/plugins/sdk-overview).
-
-<Note>
-  `@fengming/sdk` is the external app/client package for talking to the
-  Gateway. `fengming/plugin-sdk/*` is the in-process plugin authoring contract.
-  Do not import Plugin SDK subpaths from apps that only need to run agents.
-</Note>
-
-The public app SDK should be built in two layers:
-
-1. A low-level generated Gateway client.
-2. A high-level ergonomic wrapper with `FengMing`, `Agent`, `Session`, `Run`,
-   `Task`, `Artifact`, `Approval`, and `Environment` objects.
-
-## Namespace design
-
-The low-level namespaces should closely follow Gateway resources:
-
-```typescript
-oc.agents.list();
-oc.agents.get("main");
-oc.agents.create(...);
-oc.agents.update(...);
-
-oc.sessions.list();
-oc.sessions.create(...);
-oc.sessions.resolve(...);
-oc.sessions.send(...);
-oc.sessions.messages(...);
-oc.sessions.fork(...);
-oc.sessions.compact(...);
-oc.sessions.abort(...);
-
-oc.runs.create(...);
-oc.runs.get(runId);
-oc.runs.events(runId, { after });
-oc.runs.wait(runId);
-oc.runs.cancel(runId);
-
-oc.tasks.list({ status: "running" });
-oc.tasks.get(taskId);
-oc.tasks.cancel(taskId, { reason });
-oc.tasks.events(taskId, { after }); // future API
-
-oc.models.list();
-oc.models.status(); // Gateway models.authStatus
-
-oc.tools.list();
-oc.tools.invoke("tool-name", { sessionKey, idempotencyKey });
-
-oc.artifacts.list({ runId });
-oc.artifacts.get(artifactId, { runId });
-oc.artifacts.download(artifactId, { runId });
-
-oc.approvals.list();
-oc.approvals.respond(approvalId, ...);
-
-oc.environments.list();
-oc.environments.create(...); // future API: current SDK throws unsupported
-oc.environments.status(environmentId);
-oc.environments.delete(environmentId); // future API: current SDK throws unsupported
-```
-
-High-level wrappers should return objects that make common flows pleasant:
-
-```typescript
-const run = await agent.run(inputOrParams);
-await run.cancel();
-await run.wait();
-
-for await (const event of run.events()) {
-  // normalized event stream
-}
-
-const artifacts = await run.artifacts.list();
-const session = await run.session();
-```
-
-## Event contract
-
-The public SDK should expose versioned, replayable, normalized events.
-
-```typescript
-type FengMingEvent = {
-  version: 1;
-  id: string;
-  ts: number;
-  type: FengMingEventType;
-  runId?: string;
-  sessionId?: string;
-  sessionKey?: string;
-  taskId?: string;
-  agentId?: string;
-  data: unknown;
-  raw?: unknown;
-};
-```
-
-`id` is a replay cursor. Consumers should be able to reconnect with
-`events({ after: id })` and receive missed events when retention allows.
-
-Recommended normalized event families:
-
-| Event                 | Meaning                                                     |
-| --------------------- | ----------------------------------------------------------- |
-| `run.created`         | Run accepted.                                               |
-| `run.queued`          | Run is waiting for a session lane, runtime, or environment. |
-| `run.started`         | Runtime started execution.                                  |
-| `run.completed`       | Run finished successfully.                                  |
-| `run.failed`          | Run ended with an error.                                    |
-| `run.cancelled`       | Run was cancelled.                                          |
-| `run.timed_out`       | Run exceeded its timeout.                                   |
-| `assistant.delta`     | Assistant text delta.                                       |
-| `assistant.message`   | Complete assistant message or replacement.                  |
-| `thinking.delta`      | Reasoning or plan delta, when policy allows exposure.       |
-| `tool.call.started`   | Tool call began.                                            |
-| `tool.call.delta`     | Tool call streamed progress or partial output.              |
-| `tool.call.completed` | Tool call returned successfully.                            |
-| `tool.call.failed`    | Tool call failed.                                           |
-| `approval.requested`  | A run or tool needs approval.                               |
-| `approval.resolved`   | Approval was granted, denied, expired, or cancelled.        |
-| `question.requested`  | Runtime asks the user or host app for input.                |
-| `question.answered`   | Host app supplied an answer.                                |
-| `artifact.created`    | New artifact available.                                     |
-| `artifact.updated`    | Existing artifact changed.                                  |
-| `session.created`     | Session created.                                            |
-| `session.updated`     | Session metadata changed.                                   |
-| `session.compacted`   | Session compaction happened.                                |
-| `task.updated`        | Background task state changed.                              |
-| `git.branch`          | Runtime observed or changed branch state.                   |
-| `git.diff`            | Runtime produced or changed a diff.                         |
-| `git.pr`              | Runtime opened, updated, or linked a pull request.          |
-
-Runtime-native payloads should be available through `raw`, but apps should not
-have to parse `raw` for normal UI.
-
-## Result contract
-
-`Run.wait()` should return a stable result envelope:
-
-```typescript
-type RunResult = {
-  runId: string;
-  status: "accepted" | "completed" | "failed" | "cancelled" | "timed_out";
-  sessionId?: string;
-  sessionKey?: string;
-  taskId?: string;
-  startedAt?: string | number;
-  endedAt?: string | number;
-  output?: {
-    text?: string;
-    messages?: SDKMessage[];
-  };
-  usage?: {
-    inputTokens?: number;
-    outputTokens?: number;
-    totalTokens?: number;
-    costUsd?: number;
-  };
-  artifacts?: ArtifactSummary[];
-  error?: SDKError;
-};
-```
-
-The result should be boring and stable. Timestamp values preserve the Gateway
-shape, so current lifecycle-backed runs usually report epoch millisecond
-numbers while adapters may still surface ISO strings. Rich UI, tool traces, and
-runtime-native details belong in events and artifacts.
-
-`accepted` is a non-terminal wait result: it means the Gateway wait deadline
-expired before the run produced a lifecycle end/error. It must not be treated as
-`timed_out`; `timed_out` is reserved for a run that exceeded its own runtime
-timeout.
-
-## Approvals and questions
-
-Approvals must be first-class because coding agents constantly cross safety
-boundaries.
-
-```typescript
-run.onApproval(async (request) => {
-  if (request.kind === "tool" && request.toolName === "exec") {
-    return request.approveOnce({ reason: "CI command allowed by policy" });
-  }
-
-  return request.askUser();
-});
-```
-
-Approval events should carry:
-
-- approval id
-- run id and session id
-- request kind
-- requested action summary
-- tool name or environment action
-- risk level
-- available decisions
-- expiration
-- whether the decision can be reused
-
-Questions are separate from approvals. A question asks the user or host app for
-information. An approval asks for permission to perform an action.
-
-## ToolSpace model
-
-Apps need to understand the tool surface without importing plugin internals.
-
-```typescript
-const tools = await run.toolSpace();
-
-for (const tool of tools.list()) {
-  console.log(tool.name, tool.source, tool.requiresApproval);
-}
-```
-
-The SDK should expose:
-
-- normalized tool metadata
-- source: FengMing, MCP, plugin, channel, runtime, or app
-- schema summary
-- approval policy
-- runtime compatibility
-- whether a tool is hidden, readonly, write capable, or host capable
-
-Tool invocation through the SDK should be explicit and scoped. Most apps should
-run agents, not call arbitrary tools directly.
-
-## Artifact model
-
-Artifacts should cover more than files.
-
-```typescript
-type ArtifactSummary = {
-  id: string;
-  runId?: string;
-  sessionId?: string;
-  type:
-    | "file"
-    | "patch"
-    | "diff"
-    | "log"
-    | "media"
-    | "screenshot"
-    | "trajectory"
-    | "pull_request"
-    | "workspace";
-  title?: string;
-  mimeType?: string;
-  sizeBytes?: number;
-  createdAt: string;
-  expiresAt?: string;
-};
-```
-
-Common examples:
-
-- file edits and generated files
-- patch bundles
-- VCS diffs
-- screenshots and media outputs
-- logs and trace bundles
-- pull request links
-- runtime trajectories
-- managed environment workspace snapshots
-
-Artifact access should support redaction, retention, and download URLs without
-assuming every artifact is a normal local file.
-
-## Security model
-
-The app SDK must be explicit about authority.
-
-Recommended token scopes:
-
-| Scope               | Allows                                              |
-| ------------------- | --------------------------------------------------- |
-| `agent.read`        | List and inspect agents.                            |
-| `agent.run`         | Start runs.                                         |
-| `session.read`      | Read session metadata and messages.                 |
-| `session.write`     | Create, send to, fork, compact, and abort sessions. |
-| `task.read`         | Read background task state.                         |
-| `task.write`        | Cancel or modify task notification policy.          |
-| `approval.respond`  | Approve or deny requests.                           |
-| `tools.invoke`      | Invoke exposed tools directly.                      |
-| `artifacts.read`    | List and download artifacts.                        |
-| `environment.write` | Create or destroy managed environments.             |
-| `admin`             | Administrative operations.                          |
-
-Defaults:
-
-- no secret forwarding by default
-- no unrestricted environment variable pass-through
-- secret references instead of secret values
-- explicit sandbox and network policy
-- explicit remote environment retention
-- approvals for host execution unless policy proves otherwise
-- raw runtime events redacted before they leave Gateway unless the caller has a
-  stronger diagnostic scope
-
-## Managed environment provider
-
-Managed agents should be implemented as environment providers.
-
-```typescript
-type EnvironmentProvider = {
-  id: string;
-  capabilities: {
-    checkout?: boolean;
-    sandbox?: boolean;
-    networkPolicy?: boolean;
-    secrets?: boolean;
-    artifacts?: boolean;
-    logs?: boolean;
-    pullRequests?: boolean;
-    longRunning?: boolean;
-  };
-};
-```
-
-The first implementation does not need to be a hosted SaaS. It can target
-existing node hosts, ephemeral workspaces, CI-style runners, or Testbox-style
-environments. The important contract is:
-
-1. prepare workspace
-2. bind safe environment and secrets
-3. start run
-4. stream events
-5. collect artifacts
-6. clean up or retain by policy
-
-Once this is stable, a hosted cloud service can implement the same provider
-contract.
-
-## Package structure
-
-Recommended packages:
-
-| Package                 | Purpose                                                       |
-| ----------------------- | ------------------------------------------------------------- |
-| `@fengming/sdk`         | Public high-level SDK and generated low-level Gateway client. |
-| `@fengming/sdk-react`   | Optional React hooks for dashboards and app builders.         |
-| `@fengming/sdk-testing` | Test helpers and fake Gateway server for app integrations.    |
-
-The repo already has `fengming/plugin-sdk/*` for plugins. Keep that namespace
-separate to avoid confusing plugin authors with app developers.
-
-## Generated client strategy
-
-The low-level client should be generated from versioned Gateway protocol
-schemas, then wrapped by handwritten ergonomic classes.
-
-Layering:
-
-1. Gateway schema source of truth.
-2. Generated low-level TypeScript client.
-3. Runtime validators for external inputs and event payloads.
-4. High-level `FengMing`, `Agent`, `Session`, `Run`, `Task`, and `Artifact`
-   wrappers.
-5. Cookbook examples and integration tests.
-
-Benefits:
-
-- protocol drift is visible
-- tests can compare generated methods with Gateway exports
-- App SDK stays independent from Plugin SDK internals
-- low-level consumers still have full protocol access
-- high-level consumers get the small product API
-
-## Related
-
-- [FengMing App SDK](/concepts/fengming-sdk)
-- [Gateway RPC reference](/reference/rpc)
-- [Agent loop](/concepts/agent-loop)
-- [Agent runtimes](/concepts/agent-runtimes)
-- [Background tasks](/automation/tasks)
-- [ACP agents](/tools/acp-agents)
-- [Plugin SDK overview](/plugins/sdk-overview)