@xiaozhiclaw/qlogicagent-core 0.1.4 → 0.1.6

package/README.md

@@ -1,34 +1,58 @@
 # @xiaozhiclaw/qlogicagent-core
 
-Host-neutral qlogicagent turn and tool-loop runtime for server embedding.
+Shared Agent runtime for SaaS systems. AgentAtlas and AstraCAD host the same
+canonical inference/tool loop in their own existing services.
+
+The package exports three factories:
+
+- `createCloudAgent`: trusted application/tenant/actor/scope identity, fresh
+  authorization, complete structured results, checkpoints and confirmed resume.
+- `createCloudTaskRuntime`: product-owned durable tasks, cursor events, explicit
+  input/confirmation/external waits, cancellation and fenced recovery.
+- `createEmbeddedAgent`: existing low-level SaaS embedding contract.
+
+The product injects model transport, tool execution, logging, authorization and
+persistence. Login, permissions, conversations, business commits, audit, files,
+database connections and workers remain with the product. Model routing,
+credentials and accounting remain with its model service.
 
 ```ts
-import {
-  createEmbeddedAgent,
-  type LLMTransport,
-  type ToolInvoker,
-} from "@xiaozhiclaw/qlogicagent-core";
-
-const agent = createEmbeddedAgent({
-  llmTransport: transport satisfies LLMTransport,
-  toolInvoker: tools satisfies ToolInvoker,
-  apiKey: process.env.MODEL_API_KEY,
-  maxRounds: 6,
+import { createCloudAgent } from "@xiaozhiclaw/qlogicagent-core";
+
+const agent = createCloudAgent({
+  llmTransport: productModelTransport,
+  authorize: (context, action) => product.revalidateAccess(context, action),
+  checkpoints: { save: checkpoint => product.saveCheckpoint(checkpoint) },
+  onToolResult: (invocation, result) => product.saveToolReceipt(invocation, result),
+  toolInvoker: { invoke: (invocation, signal) => product.executeTool(invocation, signal) },
 });
 
 for await (const event of agent.run({
-  turnId: crypto.randomUUID(),
-  sessionId: conversationId,
-  messages,
-  tools,
-  config: { model: "model-id", maxToolCalls: 3 },
-})) {
-  // Persist or forward the typed turn events required by the host product.
+  turnId, sessionId,
+  context: { applicationId, tenantId, actorId, scopeId, definitionVersion },
+  messages, tools,
+  config: { model, maxRounds: 8, maxToolCalls: 5, maxConcurrentTools: 1 },
+}, signal)) {
+  await product.persistAndProjectEvent(event);
 }
 ```
 
-The embedding boundary owns only model/tool turn behavior. The caller retains
-authentication, tenant and conversation authority, persistence, knowledge,
-business workflows, and deployment. The package does not require the desktop
-Host, ACP, MCP, SQLite, Redis, Skills, sub-agents, filesystem tools, or shell
-tools.
+Context comes from the authenticated product, never from a model/browser claim.
+Skill knowledge is maintained by each product with its module version; MCP may
+be its tool execution protocol. The core does not install capabilities.
+
+Presentation contracts support choices, tables, diagrams, attachments and
+engineering file evidence. Each SaaS renders actual returned content blocks in
+its own UI. Tool names and paths do not imply artifacts or business success.
+
+This library has no production dependencies, CLI, desktop host, local tool
+runtime, native session store or per-process credential/policy discovery.
+Unknown tool effects require product reconciliation before recovery.
+Model retries require all three transport-error fields `retryable`, `safeToRetry`
+and `automaticRetryAuthorized` to be explicitly true (`ModelRetryAuthorization`).
+An unknown model outcome pauses a durable task for product reconciliation;
+task names and error text cannot authorize another paid inference request.
+
+See the repository's `docs/cloud-runtime.md` for detailed contracts, product
+integration boundaries and acceptance commands. Release status belongs to the
+source workspace README and package registry; this API guide is version-independent.