@native-engagement/sdk 0.8.1 → 0.9.0

package/README.md

@@ -3,7 +3,7 @@
 JavaScript and TypeScript access to Native Engagement. Requires Node.js 24.22.1+ in the 24 LTS line.
 
 ```sh
-npm install @native-engagement/sdk@0.8.1
+npm install @native-engagement/sdk@0.9.0
 ```
 
 ## Account and password sign-in
@@ -72,6 +72,56 @@ console.log(associated.entries); // Continue with associated.nextCursor when pre
 
 Creation uses an exact imported CURRENT observation, current authorization and STOP policy. It records why-fit/why-now without sending or scheduling work. Changed source rows require a new version; names, emails and domains are not stable company identifiers. Score strings retain their original scale. Original research and verification belong to the archive/Knowledge owner; Native Engagement owns imported observations, provenance, receipts and engagement facts.
 
+## Bounded discovery and task tools
+
+`sdk.discoverContracts({query, kind, limit, cursor})` reads contract metadata without whole-library schemas. Use `sdk.schema(name, 'input')` or `'output'` for selected constraints. Existing `contracts()` and `schema(name)` keep their complete response defaults.
+
+The remote SDK exports `NativeMcpToolCatalog` and `MCP_CATALOG_META_KEY` for hosts that already own an authenticated MCP client:
+
+```js
+import { NativeMcpToolCatalog } from '@native-engagement/sdk';
+
+// 每个宿主任务独立管理定义；mcpClient 继续使用原 OAuth 会话。
+const catalog = new NativeMcpToolCatalog(mcpClient);
+await catalog.initialize();
+const tools = await catalog.load({task: 'prospect-import'});
+// 将 tools 注册为本任务的模型工具；它们保留原名称、输入约束和权限元数据。
+await registerTaskTools(tools);
+const result = await catalog.call('prospect.batch.preview', originalBatch);
+```
+
+Selections may specify `task`, capability `groups`, or exact tool `names`; a new selection replaces the previous set. `catalog.refresh()` preserves the explicit selection on stateless HTTPS. Plain `tools/list` refresh gets the server default. Hosts can use the MCP protocol directly without this helper. The helper caches static definitions, never authorization or business results. Full compatibility remains available through `{mode: 'full'}`.
+
+## Logged-in browser SOCIAL clients
+
+The development and prepared thin SDK entries export `browserSocialClient`, `browserSearchScope`, `browserAccountClient` and `browserPublicationLifecycle` for Douyin/TikTok browser transport. They require a matching center and an installed, observed platform module. Their presence does not establish platform availability in an existing published package or authorize a channel account.
+
+For existing private browser conversations, `browser.autonomy(key, options)` uses the original `social.autonomy.configure` contract. A current Human must provide the exact autonomy/control versions, delegate, expiry and reply limit. Without that bounded delegation, generated text remains a draft. `browserWorkerRoutes` and the existing routed Worker reuse Work/Invocation, account waits and durable original-operation positions; the `browserSocial` selection is retained across restart. Unread media and unmapped messages require Human inspection. Public task/notification Work, publication and media ports preserve their separate approvals and require observed platform configuration. This integration does not implement an Agent Runtime.
+
+The development SDK's `browserSocialRuntimeSkill()` returns the packaged Douyin/TikTok guide and its SHA-256 digest for an existing external Runtime/role. The original `xiaohongshuRuntimeSkill()` keeps its API and canonical guide. Both use the same distribution reader; reading instructions grants no tools or action authority. These local guidance readers are not part of the thin remote-client npm entry.
+
+```js
+import { browserSocialClient } from '@native-engagement/sdk';
+
+// selectedOwner contains the canonical engagementRef, conversationRef and profileRef.
+const browser = browserSocialClient(sdk, { ...selectedOwner, platform: 'TIKTOK' });
+const retained = await browser.get();
+const activity = await browser.activity(); // Retained state only; no browser action.
+// Request freshness only when the retained Source is insufficient for the task.
+const receipt = await browser.read(originalReadKey, {
+  view: 'CONTENT', pageLimit: 1, maxItems: 20, maxExpansions: 0, maxScrolls: 0
+});
+const operation = await browser.operation(receipt.entityRefs[0]);
+```
+
+Keep the original read key and dispatch when a response is lost. Poll the original operation and use its returned window; old retained content is not evidence of the latest search. Inbox/notification reads may change the platform's read markers. Backward history supplies context and does not trigger replies to old messages.
+
+`search` registers a public query view; `adoptTarget` selects a video or author from an exact Source fact/revision. `adoptDirect` accepts an account-owned inbox thread under current registration policy. Public authors and display names cannot supply private recipients. None of these calls submits content.
+
+`draft` freezes the exact Source, complete text and `browserIntent`. `PUBLISH` also freezes video/cover Asset manifests, visibility, declarations and schedule/time zone. Queueing requires the actual current Human review; this client grants no autonomy. Preserve the original request after submission. Use `verify` for an uncertain effect; `authorizeRecovery` requires current Human review after a same-account machine update and permits original verification only. Account pause recovery uses the exact retained activity revision and preserves budgets.
+
+`browserPublicationLifecycle(message, operation, retainedView)` projects retained processing/review/schedule observations and the original approved time without browsing or dispatching. `CLIENT_VISIBLE` does not attest public delivery. Rejection, platform cancellation or a settings mismatch requires review of the original business request. `scheduleCancelDraft` and `scheduleRescheduleDraft` create separately reviewed management drafts for an exact current own scheduled POST; they do not alter the original publication request. Local `cancel` only cancels an undispatched QUEUED request. A lost management response continues with its original `verify`, never another submit.
+
 ## Batch pagination
 
 Each response has at most 100 entries; total history has no 100-batch cap. Concurrent imports can shift offset pages; restart from the first page when refreshing. Associated engagements use a separate signed cursor.