6.8 KiB
Contributions and run recovery
Before a connected workflow, call diagnostics and compare the discovered MCP tool names and input schemas with contracts/service-v1.json; its catalog digest and record-schema hashes pin the local GEWU v1 contract. Diagnostics reports the authenticated role, authorized projects/capabilities, explicit selected scope, source-transfer limits, service/catalog versions and canonical/index revisions without returning credentials or principal IDs. connection_status=authenticated proves only this call; workflow_status=not_verified means native workflow acceptance remains separate. The MCP tool inventory must match exactly. If tools are absent or schemas differ, stop before mutation and report the drift. proposal_evaluate is the deterministic preflight; the service's proposal_submit response remains authoritative. Owner decisions use a separate owner transport and are not available to agents. Runs are agent-owned, explicitly scoped service records; they do not schedule work or grant capability.
list_projects exposes authorized IDs, and get_project_context returns the selected authorized project's north star, key questions, watch list, taxonomy extensions, research lenses and explicitly saved ingest guidance without exposing its autonomy policy. Projects default to technical, conceptual, cultural-historical and financial-market lenses. These are coverage prompts, not quotas. Use this context for ingest/curation; keep objective and scope explicit and never infer authority from a folder or project name.
When available, ingest_review_create stores a source-bound review flag. Submit it after or alongside normal proposal processing, never as a reason to wait on human review before evaluating/submitting plausible findings. Bind it to the durable run and an extraction owned by the submitting agent and granted project; the exact excerpt and locator must match the staged extraction. A queue entry is a notification/filter and feedback record, not a proposal, source registration, acceptance result or publication. Human reviewers may confirm relevance, mark it irrelevant or defer feedback. Reusable project guidance is added to future context only when a human explicitly saves a rule. If the review operation is absent, preserve and report plausible uncertain material rather than silently deferring it.
Current capability gaps that must be reported when relevant: retrieval is lexical only; URL capture requires an exact operator-allowlisted public host. URL and selected-file intake support UTF-8 text/Markdown/HTML and PDF; selected .vtt and .srt files are parsed into timestamped cues and tagged capture_method=transcript. Transcript evidence must cite the exact text span and matching cue start/end milliseconds. source_capture_text accepts explicitly supplied UTF-8 plain text or Markdown up to 1 MB. It requires a stable capture ID, stores the completed metadata candidate in a private bounded receipt journal, returns the same candidate for an exact retry, and conflicts if the same ID is reused with changed inputs. Source records distinguish URL fetch, local-file, transcript, declared NotebookLM-export and pasted-text capture methods; the NotebookLM label does not verify export provenance. HTML citations refer to the visible-text extraction, not markup-byte offsets. PDF extraction is qualified only on Linux in a sandbox; scanned PDFs return PDF_NO_TEXT. Failed URL captures can be registered as artifact-free references, and source records include publisher, author, publication date, license and reliability fields. supplied NotebookLM exports, Windows/macOS PDF extraction, native host workflows and real-source location checks remain unqualified. There are no vector/hybrid search or project-export/import operations. Duplicate review can nominate exact entity name/alias matches only within the caller-readable explicit scope; it does not merge records. Reversible merge, protected owner decisions, promotion and synthesis-dependency warnings remain unavailable. Do not describe these as implemented merely because a pipeline or record schema can represent related data.
Use read tools for retrieval and typed MCP proposals for contributions. Source upload completion establishes a staged artifact, not an accepted source. Treat policy acceptance and index visibility as separate outcomes. Corrections append revisions; accepted records are corrected through new linked proposals.
Create the service run with run_create before capture or proposal submission. Persist returned run identity and operation input digests in the private local checkpoint, then append service checkpoints with run_checkpoint; run_status is authoritative after uncertain calls and returns the latest revision. Each update uses expected_revision; retry the same checkpoint unchanged after uncertainty. The local helper remains a private host-side recovery mirror and is useful when offline. Checkpoints include pack/skill/pipeline versions and hashes, explicit project/shared scope and lens, source/extraction references, stage, output hashes, included/excluded/skipped coverage, pending side effects and last receipt. The helper rejects credential/source-body fields and verifies pinned module hashes on resume. The pack does not provide a host scheduler.
Use the checkpoint contract in the pack README and resolve the module registry in the manifest. Record its snapshot digest and every applicable module's contract ID/version and file hash, including the profile and shared protocols. Verify those hashes before resuming; a mismatch requires the original snapshot or an explicitly revalidated successor run.
When upload completion is uncertain, call source_upload_status with the saved upload ID and resume only from its verified offsets. When proposal submission is uncertain, call proposal_status with the same proposal ID and revision. If accepted, reuse the returned receipt and do not resubmit. If evaluated but not accepted, inspect findings; if withdrawn, that proposal revision cannot be submitted. Never generate a fresh proposal ID to hide network uncertainty. Resume from preserved artifacts and service receipts; changed content requires a new proposal revision. Do not rerun a model and assume it reproduces the same output.
Bound work by source/batch size, stage/model budget and correction attempts. After two unchanged validation failures, stop for diagnosis and report findings. Coverage/skips remain explicit at any stop. Cancellation cannot undo an accepted proposal; check status when a call may have completed.
Only the service decides acceptance. Report accepted, held/rejected, index-pending and blocked work separately. Human-owned intent/policy changes need a distinct authenticated owner decision; the agent cannot supply it or hold owner credentials. An installed skill grants no authority beyond the user's task and current service credential.