@margay/ccl-core 1.4.5-rc.9 → 1.5.0-alpha.0

package/examples/assistant/office/check.py

@@ -0,0 +1,174 @@
+#!/usr/bin/env python3
+"""Independent mechanical Office checks. No inference and no semantic verdict.
+Usage: python3 check.py INPUT_DIRECTORY OUTPUT_DIRECTORY
+stdout: one JSON report; exit 0 mechanical pass, 1 mismatch, 2 invalid input.
+"""
+import csv
+import hashlib
+import json
+import math
+import sys
+import zipfile
+from pathlib import Path
+from xml.etree import ElementTree as ET
+
+NS = {'w': 'http://schemas.openxmlformats.org/wordprocessingml/2006/main',
+      'a': 'http://schemas.openxmlformats.org/drawingml/2006/main',
+      'p': 'http://schemas.openxmlformats.org/presentationml/2006/main',
+      'r': 'http://schemas.openxmlformats.org/officeDocument/2006/relationships',
+      'c': 'http://schemas.openxmlformats.org/drawingml/2006/chart'}
+
+def sha(path):
+    return hashlib.sha256(path.read_bytes()).hexdigest()
+
+def source_facts(inputs):
+    def rows(name):
+        with (inputs / name).open(encoding='utf-8-sig', newline='') as f:
+            return list(csv.DictReader(f))
+    monthly, channels = rows('monthly.csv'), rows('channels.csv')
+    if len(monthly) < 2 or not channels:
+        raise ValueError('At least two monthly rows and one channel are required')
+    monthly.sort(key=lambda row: row['month'])
+    months = [row['month'] for row in monthly]
+    if len(set(months)) != len(months):
+        raise ValueError('Duplicate months')
+    for rows_ in (monthly, channels):
+        for row in rows_:
+            for key in ('revenue', 'cost', 'orders'):
+                if key in row:
+                    row[key] = float(row[key])
+                    if not math.isfinite(row[key]) or row[key] < 0:
+                        raise ValueError(f'Invalid {key}')
+    if any(row['revenue'] <= 0 for row in monthly):
+        raise ValueError('Revenue must be positive for ratio calculations')
+    revenue = sum(row['revenue'] for row in monthly)
+    channel_total = sum(row['revenue'] for row in channels)
+    if not math.isclose(revenue, channel_total, abs_tol=.01):
+        raise ValueError('Monthly and channel revenue disagree; resolve source scope first')
+    cost = sum(row['cost'] for row in monthly)
+    series = [{**row, 'gross_profit': row['revenue'] - row['cost'],
+               'cost_ratio': row['cost'] / row['revenue'],
+               'gross_margin': (row['revenue'] - row['cost']) / row['revenue'],
+               'revenue_mom': None if i == 0 else row['revenue'] / monthly[i-1]['revenue'] - 1}
+              for i, row in enumerate(monthly)]
+    top = max(channels, key=lambda row: row['revenue'])
+    highest_cost = max(series, key=lambda row: row['cost_ratio'])
+    metrics = {'revenue': revenue, 'cost': cost, 'gross_profit': revenue - cost,
+               'gross_margin': (revenue - cost) / revenue,
+               'revenue_growth': monthly[-1]['revenue'] / monthly[0]['revenue'] - 1,
+               'top_channel': top['channel'], 'top_channel_share': top['revenue'] / revenue,
+               'highest_cost_ratio_month': highest_cost['month'],
+               'highest_cost_ratio': highest_cost['cost_ratio'],
+               'revenue_monotonically_increasing': all(row['revenue_mom'] > 0 for row in series[1:])}
+    return {'period': [months[0], months[-1]], 'metrics': metrics, 'monthly': series, 'channels': channels,
+            'formulas': {'gross_margin': '(sum(revenue)-sum(cost))/sum(revenue)',
+                         'revenue_growth': 'last_month_revenue/first_month_revenue-1',
+                         'cost_ratio': 'month_cost/month_revenue',
+                         'revenue_mom': 'month_revenue/previous_month_revenue-1',
+                         'top_channel_share': 'largest_channel_revenue/sum(revenue)'},
+            'sources': {name: sha(inputs / name) for name in ('monthly.csv', 'channels.csv')}}
+
+def xml(package, path):
+    return ET.fromstring(package.read(path))
+
+def text(node, prefix):
+    return ''.join(element.text or '' for element in node.findall('.//' + prefix + ':t', NS))
+
+def embedded_media(package, part):
+    """Count distinct images/native charts actually referenced by this part."""
+    root = xml(package, part)
+    ids = [e.get('{' + NS['r'] + '}embed') for e in root.findall('.//a:blip', NS)]
+    ids += [e.get('{' + NS['r'] + '}id') for e in root.findall('.//c:chart', NS)]
+    path = Path(part)
+    rels = xml(package, str(path.parent / '_rels' / (path.name + '.rels')))
+    targets = {e.get('Id'): e for e in rels}
+    hashes = set()
+    for id_ in ids:
+        rel = targets.get(id_)
+        if rel is None or rel.get('TargetMode') == 'External':
+            raise ValueError(f'{part}: unresolved/external media {id_}')
+        import posixpath
+        target = posixpath.normpath(posixpath.join(str(path.parent), rel.get('Target', '')))
+        if target.startswith('/'):
+            target = target.lstrip('/')
+        hashes.add(hashlib.sha256(package.read(target)).hexdigest())
+    return hashes
+
+def inspect_docx(path):
+    with zipfile.ZipFile(path) as package:
+        root = xml(package, 'word/document.xml')
+        body = root.find('w:body', NS)
+        paragraphs = []
+        for paragraph in body.findall('w:p', NS):
+            style = paragraph.find('w:pPr/w:pStyle', NS)
+            style_id = style.get('{' + NS['w'] + '}val', 'Normal') if style is not None else 'Normal'
+            if style_id in ('Normal', 'BodyText', 'BodyText2', 'BodyText3'):
+                paragraphs.append(text(paragraph, 'w'))
+        # The task defines Chinese body characters, excluding tables, titles and captions.
+        count = sum(1 for paragraph in paragraphs for char in paragraph
+                    if '\u3400' <= char <= '\u4dbf' or '\u4e00' <= char <= '\u9fff' or '\U00020000' <= char <= '\U0002fa1f')
+        return {'body_han_characters': count, 'body_paragraphs': paragraphs,
+                'full_text': text(body, 'w'),
+                'embedded_media_count': len(embedded_media(package, 'word/document.xml'))}
+
+def inspect_pptx(path):
+    with zipfile.ZipFile(path) as package:
+        presentation = xml(package, 'ppt/presentation.xml')
+        size = presentation.find('p:sldSz', NS)
+        rels = {r.get('Id'): r.get('Target') for r in xml(package, 'ppt/_rels/presentation.xml.rels')}
+        parts = []
+        import posixpath
+        for slide in presentation.findall('p:sldIdLst/p:sldId', NS):
+            target = rels[slide.get('{' + NS['r'] + '}id')]
+            parts.append(target.lstrip('/') if target.startswith('/') else posixpath.normpath('ppt/' + target))
+        media = set()
+        texts = []
+        for part in parts:
+            texts.append(text(xml(package, part), 'a'))
+            media |= embedded_media(package, part)
+        return {'slide_count': len(parts), 'ratio': int(size.get('cx')) / int(size.get('cy')),
+                'slides_text': texts, 'embedded_media_count': len(media)}
+
+def check(inputs, outputs):
+    facts = source_facts(inputs)
+    metrics = json.loads((outputs / 'metrics.json').read_text(encoding='utf8'))
+    # Deliberately read only for deliverable validity; model assertions are not a verdict.
+    json.loads((outputs / 'validation.json').read_text(encoding='utf8'))
+    docx, pptx = inspect_docx(outputs / 'report.docx'), inspect_pptx(outputs / 'presentation.pptx')
+    failures = []
+    for key, expected in facts['metrics'].items():
+        actual = metrics.get(key)
+        if isinstance(expected, bool) or isinstance(expected, str):
+            equal = type(actual) is type(expected) and actual == expected
+        else:
+            equal = type(actual) in (int, float) and math.isfinite(actual) and math.isclose(actual, expected, rel_tol=1e-5, abs_tol=1e-6)
+        if not equal:
+            failures.append({'check': 'metric.' + key, 'expected': expected, 'actual': actual})
+    for ok, name, expected, actual in [
+        (docx['body_han_characters'] >= 1000, 'docx.body_han_characters', '>=1000', docx['body_han_characters']),
+        (pptx['slide_count'] == 6, 'pptx.slide_count', 6, pptx['slide_count']),
+        (math.isclose(pptx['ratio'], 16 / 9, abs_tol=.001), 'pptx.aspect_ratio', '16:9', pptx['ratio']),
+        (docx['embedded_media_count'] >= 2, 'docx.embedded_media', '>=2 distinct', docx['embedded_media_count']),
+        (pptx['embedded_media_count'] >= 2, 'pptx.embedded_media', '>=2 distinct', pptx['embedded_media_count']),
+    ]:
+        if not ok:
+            failures.append({'check': name, 'expected': expected, 'actual': actual})
+    return {'schema_version': 1, 'mechanical': 'failed' if failures else 'passed',
+            'semantic': 'unverified', 'overall': 'failed' if failures else 'unverified',
+            'failures': failures, 'facts': facts, 'docx': docx, 'pptx': pptx,
+            'artifacts': {name: sha(outputs / name) for name in ('report.docx', 'presentation.pptx', 'metrics.json', 'validation.json')},
+            'review_required': ['Read full Word and all slide text against source facts and supplied brief/meeting notes.',
+                                'Inspect every rendered page/slide for clipping, readable labels and at least two genuine data charts in each document.',
+                                'Check at least four actionable proposals with suggested owner, date and measurable acceptance criterion.',
+                                'Separate established facts, meeting observations and proposals; do not infer unsupported causation or unavailable metrics.']}
+
+if __name__ == '__main__':
+    try:
+        if len(sys.argv) != 3:
+            raise ValueError('Usage: check.py INPUT_DIRECTORY OUTPUT_DIRECTORY')
+        report = check(Path(sys.argv[1]), Path(sys.argv[2]))
+        print(json.dumps(report, ensure_ascii=False, indent=2))
+        sys.exit(0 if report['mechanical'] == 'passed' else 1)
+    except Exception as error:
+        print(json.dumps({'schema_version': 1, 'mechanical': 'error', 'semantic': 'unverified', 'overall': 'failed', 'error': str(error)}, ensure_ascii=False))
+        sys.exit(2)

package/examples/assistant/office/render.py

@@ -0,0 +1,99 @@
+#!/usr/bin/env python3
+"""Render every page through isolated LibreOffice, then PyMuPDF. Never uses an open office window."""
+import argparse
+import hashlib
+import json
+import os
+from pathlib import Path
+import signal
+import subprocess
+import tempfile
+
+
+def digest(path):
+    return hashlib.sha256(path.read_bytes()).hexdigest()
+
+
+def previous_pages(output):
+    """Recover only this renderer's page names; unknown metadata grants no ownership."""
+    path = output / 'manifest.json'
+    if path.is_symlink():
+        return {}
+    try:
+        manifest = json.loads(path.read_text(encoding='utf8'))
+    except (OSError, ValueError):
+        return {}
+    if not isinstance(manifest, dict) or not isinstance(manifest.get('documents'), list):
+        return {}
+    pages = {}
+    for document in manifest['documents']:
+        if not isinstance(document, dict) or document.get('source') not in ('report.docx', 'presentation.pptx'):
+            continue
+        if not isinstance(document.get('pages'), list):
+            continue
+        for page in document['pages']:
+            if not isinstance(page, dict) or type(page.get('page')) is not int or page['page'] < 1:
+                continue
+            name = Path(document['source']).stem + f"-page-{page['page']:03d}.png"
+            if page.get('path') == name and isinstance(page.get('sha256'), str):
+                pages[name] = page['sha256']
+    return pages
+
+
+def render(soffice, source, output):
+    import pymupdf as fitz
+    source, output = source.resolve(), output.resolve()
+    output.mkdir(parents=True, exist_ok=True)
+    previous = previous_pages(output)
+    manifest = {'renderer': str(Path(soffice).resolve()), 'documents': []}
+    with tempfile.TemporaryDirectory(prefix='ccl-office-render-') as own:
+        profile = (Path(own) / 'profile').as_uri()
+        for name in ('report.docx', 'presentation.pptx'):
+            original = source / name
+            # Fresh conversion directory prevents accidentally accepting an old PDF.
+            conversion = Path(own) / name
+            conversion.mkdir()
+            command = [soffice, '-env:UserInstallation=' + profile, '--headless', '--convert-to', 'pdf', '--outdir', str(conversion), str(original)]
+            child = subprocess.Popen(command, stdout=subprocess.PIPE, stderr=subprocess.STDOUT,
+                                     start_new_session=True, env={**os.environ, 'TMPDIR': own})
+            try:
+                log, _ = child.communicate(timeout=120)
+            except subprocess.TimeoutExpired:
+                os.killpg(child.pid, signal.SIGTERM)
+                try: child.communicate(timeout=5)
+                except subprocess.TimeoutExpired:
+                    os.killpg(child.pid, signal.SIGKILL)
+                    child.communicate()
+                raise RuntimeError('Office conversion timed out: ' + name)
+            pdf = conversion / (Path(name).stem + '.pdf')
+            if child.returncode != 0 or not pdf.is_file():
+                raise RuntimeError('Office conversion failed: ' + log.decode(errors='replace')[-2000:])
+            destination = output / pdf.name
+            destination.write_bytes(pdf.read_bytes())
+            pages = []
+            with fitz.open(destination) as document:
+                for index, page in enumerate(document):
+                    image = output / (pdf.stem + f'-page-{index + 1:03d}.png')
+                    page.get_pixmap(matrix=fitz.Matrix(1.5, 1.5), alpha=False).save(image)
+                    pages.append({'page': index + 1, 'path': image.name, 'sha256': digest(image)})
+            if not pages:
+                raise RuntimeError('Renderer returned no pages: ' + name)
+            manifest['documents'].append({'source': name, 'source_sha256': digest(original), 'pdf': destination.name,
+                                          'pdf_sha256': digest(destination), 'pages': pages})
+    # Both conversions succeeded. Remove only unchanged obsolete pages owned by
+    # the previous manifest; preserve unlisted files, user edits and symlinks.
+    current = {page['path'] for document in manifest['documents'] for page in document['pages']}
+    for name, sha256 in previous.items():
+        path = output / name
+        if name not in current and not path.is_symlink() and path.is_file() and digest(path) == sha256:
+            path.unlink()
+    (output / 'manifest.json').write_text(json.dumps(manifest, ensure_ascii=False, indent=2), encoding='utf8')
+    print(json.dumps(manifest, ensure_ascii=False))
+
+if __name__ == '__main__':
+    parser = argparse.ArgumentParser()
+    parser.add_argument('--soffice', required=True)
+    parser.add_argument('source', type=Path)
+    parser.add_argument('output', type=Path)
+    args = parser.parse_args()
+    render(args.soffice, args.source, args.output)

package/examples/assistant/office/workflow.md

@@ -0,0 +1,46 @@
+# 制作与验收
+
+本目录随 npm 包发布。命令里的 WORKFLOW 指本目录的绝对路径；INPUT/OUTPUT 是调用者提供的任务目录。原件留在 INPUT，产物写入 OUTPUT。中文字体和渲染依赖以运行环境实际可用项为准。
+
+制作依赖：Python 3、python-docx、python-pptx、Pillow。独立 `check.py` 只使用 Python 标准库。缺依赖时使用任务自己的虚拟环境安装，或采用已授权且能满足相同合同的制品工具，不改用户全局环境。
+
+模板 `build.py` 接受如下 `content.json`（这里是结构示意，正文与分析由助手根据本次材料写）：
+
+```json
+{
+  "title": "报告标题",
+  "subtitle": "期间、人民币元、编制日期",
+  "sections": [{"title":"章节", "paragraphs":["完整正文段落"], "chart":"monthly", "caption":"图注及来源"}],
+  "actions": [{"action":"建议行动", "owner":"建议负责人", "date":"建议日期", "metric":"可检查指标"}],
+  "slides": [{"title":"页标题", "bullets":["观点和依据"], "chart":"channels"}],
+  "metrics": {"revenue":0,"cost":0,"gross_profit":0,"gross_margin":0,"revenue_growth":0,"top_channel":"渠道","top_channel_share":0,"highest_cost_ratio_month":"YYYY-MM","highest_cost_ratio":0,"revenue_monotonically_increasing":false},
+  "author_checks": ["作者已完成的具体检查"]
+}
+```
+
+sections/slides 的 chart 可省略；支持 monthly（收入和成本）、channels（渠道收入），每份文档都应含二者。slides 提供 6 项；actions 至少 4 项；正文写足实质分析。比例使用 0–1 数值。输入 CSV 字段分别为 `month,revenue,cost,orders` 与 `channel,revenue,orders`，此外读取用户提供的业务简报与会议材料。别的结构应先做显式映射、保留原件与映射记录，不把未知单位默认为人民币。
+
+写分析前，明确每项比较的起点、终点、分母和期间。首月与末月的变化只能称“末月较首月”，不能改称半年累计增长或同比；同比需要上一年同期数据。收入、成本率、毛利率各自检查完整月度序列：首尾改善不意味着逐月改善，中途反向变化要在 Word 与 PPT 中一致披露，不在另一段又称单调变化。不要把不同月份的数值合并成同一个值。
+
+把可观察事实、业务假设、会议观察和建议分别表述。成本率下降本身不能证明固定成本摊薄、采购提效或交付改善；没有成本拆分与运营数据时，把这些作为待验证解释，不能在正文、图注或 PPT 中改写成已证实原因。收入和订单数据也不能证明获客触点、低成本渠道或未来增长潜力。只对明确推导的比率作数值结论，其他判断给出已有依据或注明需要验证。
+
+Word 的行动表与 PPT 的行动页分别能够独立使用：至少四项行动都给出建议负责人、建议日期和可检查指标；“建议”标识可用全页说明，不能只在 Word 写完整而在 PPT 丢失日期和验收指标。内容过密时优先压缩重复叙述、调整版式，不能删除决策所需字段。
+
+```sh
+python3 "$WORKFLOW/build.py" "$INPUT" content.json "$OUTPUT"
+python3 "$WORKFLOW/check.py" "$INPUT" "$OUTPUT" > independent-check.json
+```
+
+build 替换 OUTPUT 中 report.docx、presentation.pptx、metrics.json、validation.json、monthly.png、channels.png；非零退出需读错误并修复具体原因。模板图表取自 CSV，报告正文和 metrics 取自 content.json；不从检查器复制计算来伪造独立比较。可修改模板布局或直接编辑 Office 文件，但再次检查实际最终文件。
+
+check 从 CSV 重新计算事实，直接解析 Office 文件；输出 JSON 含输入/产物哈希、实际正文汉字数、页数、比例、内嵌媒体数量、全文、事实表及差异。0 只表示机械检查通过；1 表示差异，2 表示输入/制品不可解析。内嵌媒体检查证明有不同图片/原生图表，不证明它们是正确数据图；独立审阅须检查。`semantic`/`overall` 不因机械检查通过自动变绿。源材料的会议观察、因果陈述、行动可行性须审阅全文，不用关键词正则裁判。
+
+用真实 Office 渲染器导出两个制品的全部页面，再逐页检查。若调用者明确由宿主渲染，以下命令由宿主执行；生成助手完成制品和机械检查后交回，不在代理沙箱内查找、启动或排障渲染器。`render.py` 使用给定 LibreOffice 可执行文件，独立用户配置与输出目录，不调用用户正在使用的 Office 窗口。需要 PyMuPDF 将 PDF 每页转 PNG。执行：
+
+```sh
+python3 "$WORKFLOW/render.py" --soffice /absolute/path/to/soffice "$OUTPUT" "$OUTPUT/rendered"
+```
+
+返回 manifest.json 包含源文件哈希、PDF/全部页图片哈希和页数；按本次 manifest 及哈希选取审阅页面，不把目录中其他图片当作当前页面。复用输出目录时，两个制品均成功转换后，渲染器只清除上次 manifest 记录、内容未被修改且本次已不再存在的旧页；未登记文件、用户修改过的文件和符号链接保留。调用者提供渲染器/Python 路径时直接使用。未提供时只检查 PATH 和系统标准安装位置一次；确认缺失后，在任务目录准备依赖或报告具体依赖缺口，继续完成不依赖渲染的部分。不要重复全盘搜索或用像素数量、XML 抽取、自制近似 PDF 替代真实渲染。只看首页不能称为版式验收。渲染完成后交给现有独立审阅者；没有独立审阅能力时保存全部页面并报告待审，不虚构另一个审阅者。
+
+独立审阅者应读取原简报、会议记录、CSV、independent-check.json、报告全文和 manifest 的全部页面，逐条判断：事实/趋势/极值正确；会议观察与建议分开；至少 4 条建议各有建议负责人、日期、可检查指标；图表真实且无裁切、遮挡、字号过小。记录看到的文件哈希和具体页/段问题，留存审阅来源。修复后只复核受影响内容及结构，不制造自签独立 PASS。

package/examples/assistant/terminal.mjs

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+import { createInterface } from 'node:readline'
+import { parseArgs } from 'node:util'
+import { AssistantClient } from './client.mjs'
+
+const { values } = parseArgs({ options: {
+  cwd: { type: 'string' }, 'state-dir': { type: 'string' }, model: { type: 'string' },
+  resume: { type: 'boolean' }, 'cli-path': { type: 'string' }, 'extra-args': { type: 'string' }, help: { type: 'boolean' },
+} })
+if (values.help) {
+  console.log('node terminal.mjs [--cwd PROJECT] [--state-dir DIR] [--model MODEL] [--resume]\nCommands: /status, /steer TEXT, /cancel [TURN_ID], /allow TOOL_ID, /deny TOOL_ID, /defer TOOL_ID, /artifact FILE, /office ["INPUT","OUTPUT"], /verify-office ["INPUT","OUTPUT"], /exit\nExecution, verification and file availability are separate. Restart with --resume; uncertain work is never replayed automatically.')
+  process.exit(0)
+}
+let textOpen = false
+function line(message) { if (textOpen) { process.stdout.write('\n'); textOpen = false }; console.log(message) }
+function display(event) {
+  if (event.type === 'text_delta') { process.stdout.write(event.text); textOpen = true; return }
+  if (event.type === 'connected') line(`[连接] session=${event.sessionId} pid=${event.pid}`)
+  else if (event.type === 'turn_queued') line(`[排队] ${event.turnId}`)
+  else if (event.type === 'turn_started') line(`[已发送] ${event.turnId}，等待执行响应`)
+  else if (event.type === 'turn_cancel_requested') line(`[取消请求] ${event.turnId}；已发生的操作不会撤销`)
+  else if (event.type === 'turn_finished') line(`[执行结束] ${event.turnId}: ${event.outcome}`)
+  else if (event.type === 'execution_result') line(`[验证] ${event.verification}；执行结果不等于独立验收`)
+  else if (event.type === 'tool_use') line(`[工具] ${event.toolName}`)
+  else if (event.type === 'request_progress') line(`[请求] ${event.progress.phase}`)
+  else if (event.type === 'approval') line(`[等待权限] ${event.toolName} ${JSON.stringify(event.input)}\n/allow ${event.toolUseId} 或 /deny ${event.toolUseId}；/defer ${event.toolUseId} 保存后再决定`)
+  else if (event.type === 'suspended') line(`[权限已保存] ${event.toolUseId}；可退出并用 --resume 恢复后批准/拒绝`)
+  else if (event.type === 'independent_check') line(`[独立检查] 数值/结构=${event.verification.mechanical}，内容审阅=${event.verification.semantic}\n${JSON.stringify(event.verification.report.failures ?? event.verification.report.error)}`)
+  else if (event.type === 'artifact_available') line(`[交付] ${event.artifact.path} 可读取，${event.artifact.bytes} 字节；内容验证另行完成`)
+  else if (['diagnostic', 'turn_error', 'error'].includes(event.type)) line(`[诊断] ${event.message}`)
+}
+const client = new AssistantClient({ cwd: values.cwd, stateDirectory: values['state-dir'], model: values.model,
+  cliPath: values['cli-path'], resume: values.resume, extraArgs: values['extra-args'] ? JSON.parse(values['extra-args']) : undefined,
+  onDisplay: display })
+const input = createInterface({ input: process.stdin, terminal: !!process.stdin.isTTY })
+let exiting = false
+async function exit() { if (exiting) return; exiting = true; input.close(); await client.close() }
+input.on('line', text => {
+  const [command, ...args] = text.trim().split(/\s+/)
+  const rest = args.join(' ')
+  void (async () => {
+    if (command === '/exit') await exit()
+    else if (command === '/status') line(JSON.stringify(client.status(), null, 2))
+    else if (command === '/steer') client.prompt(rest, true)
+    else if (command === '/cancel') await client.cancel(rest || undefined)
+    else if (['/allow', '/deny', '/defer'].includes(command)) await client.decide(rest, command === '/defer' ? 'pending' : command.slice(1))
+    else if (command === '/artifact') client.artifact(rest)
+    else if (['/office', '/verify-office'].includes(command)) {
+      const paths = JSON.parse(rest)
+      if (!Array.isArray(paths) || paths.length !== 2 || paths.some(path => typeof path !== 'string')) throw new Error('Use ["INPUT_DIRECTORY","OUTPUT_DIRECTORY"]')
+      if (command === '/office') client.office(...paths)
+      else await client.verifyOffice(...paths)
+    }
+    else if (text.trim()) client.prompt(text)
+  })().catch(error => line(`[错误] ${String(error)}`))
+})
+input.on('close', () => { if (!exiting) void client.drain().finally(exit) })
+process.once('SIGINT', () => { void client.cancel().catch(error => line(String(error))) })
+process.once('SIGTERM', () => { void exit() })
+line('输入任务，或 /status 查看执行、验证与交付状态。')

package/package.json

@@ -1,16 +1,18 @@
 {
   "name": "@margay/ccl-core",
-  "version": "1.4.5-rc.9",
+  "version": "1.5.0-alpha.0",
   "description": "Core runtime extracted from Claude Code (ccl) for Margay integration",
   "license": "SEE LICENSE IN README.md",
   "type": "module",
   "bin": {
+    "ccl": "dist/cli.js",
     "margay": "dist/cli.js"
   },
   "files": [
     "dist",
     "README.md",
     "QUICKSTART.md",
+    "docs/cli-installation.md",
     "INTENT-GATEWAY-GUIDE.md",
     "docs/index.md",
     "docs/error-recovery-usage.md",
@@ -37,10 +39,15 @@
     "docs/features/business-facts.md",
     "docs/releases/1.4.5-rc.8.md",
     "docs/features/copy-on-select.md",
-    "docs/releases/1.4.5-rc.9.md"
+    "docs/releases/1.4.5-rc.9.md",
+    "docs/releases/1.4.5-rc.10.md",
+    "docs/context-checkpoints-and-daemon.md",
+    "docs/releases/1.4.6-beta.0.md",
+    "examples/assistant",
+    "docs/releases/1.5.0-alpha.0.md"
   ],
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=22.19.0"
   },
   "scripts": {
     "typecheck": "tsc --noEmit",
@@ -128,7 +135,7 @@
     "tree-kill": "^1.2.2",
     "turndown": "^7.2.4",
     "type-fest": "^5.5.0",
-    "undici": "^8.0.2",
+    "undici": "8.0.2",
     "usehooks-ts": "^3.1.1",
     "vscode-jsonrpc": "^8.2.1",
     "vscode-languageserver-protocol": "^3.17.5",

package/sdk/API.md

@@ -17,7 +17,7 @@ import {
 } from '@margay/ccl-core/sdk'
 ```
 
-- **运行时**:Node ≥ 20(ESM)。SDK 本体零第三方依赖,只用 Node 内置模块。
+- **运行时**:Node ≥ 22.19.0（ESM），依赖随 `@margay/ccl-core` 安装。
 - **CLI 定位**:SDK 以受管子进程方式运行 CCL CLI(全管道 stdio,无 TTY)。CLI 路径解析顺序:
   1. `options.cliPath`
   2. 环境变量 `CCL_SDK_CLI_PATH`
@@ -29,10 +29,16 @@ import {
 
 ## 2. 核心入口
 
-### 2.1 `query(prompt, options?) → AsyncGenerator<SDKEvent>`
+### 2.1 `query({ prompt, options? }) → Query`
 
 发起一轮对话(一次 agentic 任务),异步迭代产出事件,直到终态事件(`result` / `suspended` / fatal `error`)后结束。
 
+上面的单轮语义适用于字符串输入；旧的双参数形式仍兼容。`prompt` 也可传
+`AsyncIterable<SDKUserMessage>`：每条输入完成后再消费下一条，`result.turnId`
+关联输入的 `uuid`（未提供时自动生成）。输入结束、生成器错误、abort 或 close
+都会回收流式 query 的 CLI 进程。必须持续消费事件；流式输出积压超过 1024 项
+会明确报错并关闭，避免无限占用内存。
+
 ```ts
 for await (const event of query('检查收件箱并起草回复', {
   cwd: '/srv/cos-workspace',
@@ -73,6 +79,36 @@ for await (const event of resumeWithDecision(sessionId, { behavior: 'allow' }))
 
 `query(newPrompt, { resume: sessionId })` —— 在已有会话上继续新一轮对话(非审批场景的普通 resume)。
 
+### 2.5 `createSession(options?) → Session`
+
+在同一个 CLI 进程中连续交互。`prompt(content)`、`followUp(content)` 返回
+`Turn { id, result, cancel() }`，按顺序执行；`steer(content)` 中断当前轮，将纠偏
+放到等待队列前面。已产生的工具副作用不会回滚。
+
+`maxPendingTurns` 默认 32，包含正在执行的轮次，队满时同步拒绝新输入。
+`onEvent(event)` 接收即时事件，Session 不保存事件历史。`controls` 提供原有
+Query 控制方法，`pid` 用于宿主监控。
+
+`onLifecycle(event: SessionLifecycleEvent)` 单独观察宿主状态，不增加模型调用。
+所有通知含 `at`（毫秒）、`pendingTurns`，可用时附 `pid`/`sessionId`：
+
+- `turn_queued`：接受入队；`turn_started`：输入已写入 CLI，尚不代表模型已响应。
+- `turn_cancel_requested`：已请求中断；已执行操作仍可能有副作用。
+- `turn_finished`：`succeeded`/`failed`/`cancelled`/`interrupted`/`suspended`；其中 `cancelled` 为尚未发送的队列项。
+- `permission_waiting`/`permission_resolved`：请求 ID、工具 ID/名称或决定。
+- `session_closed`：执行通道关闭及原因。
+
+回调异常不终止执行；耗时工作应由宿主另行排队。执行成功不等于产物验证通过。
+通过 `Session.interrupt()` 或 `Turn.cancel()` 请求取消，才能观察宿主取消通知；
+`controls` 是底层控制通道，直接调用其 interrupt 不经过宿主队列状态。
+`SDKEvent.origin` 的 `user`/`background` 与 `turnId` 用于区分用户输入和自主工作；
+旧 CLI 没有显式来源时保持兼容归属，不能据此证明后台来源。
+参考终端、状态恢复与权限操作见 [assistant 示例](../examples/assistant/README.md)。
+
+`endInput()` 停止接受新输入并等待已接受轮次，但保留进程和控制通道；`close()`
+终止进程并拒绝未完成轮次。权限回调可等待宿主决定，interrupt/close 会取消
+等待；返回 `pending` 仍表示持久挂起，后续用 `resumeWithDecision` 恢复。
+
 ---
 
 ## 3. 事件参考(SDKEvent)
@@ -92,7 +128,9 @@ for await (const event of resumeWithDecision(sessionId, { behavior: 'allow' }))
 | `error_diagnostic` | `diagnostic: RecoveryDiagnostic`, `sessionId?` | 可选过程事件，仅 `includeErrorDiagnostics:true` 时输出；不是终态 |
 | `raw` | `message` | 透传子进程原始消息(仅 `includeRaw:true` 时产出,调试用) |
 
-**终态约定**:每次迭代**恰好一个**终态——`result`、`suspended`、或 fatal `error`。宿主状态机据此收敛。
+**终态约定**：字符串 query 的 `result` 结束该次输入。流式 query / Session 的
+`result` 只结束对应 `turnId`，后续仍可能有输入。`suspended`、fatal `error`、
+关闭或输入 EOF 结束流式 query；不要把首个 result 当作常驻 Session 已关闭。
 
 ### 恢复结果与用户介入
 
@@ -390,3 +428,13 @@ query('用 filesystem server 列目录', {
 
 新增事件:`{ type:'stream_event', event, sessionId? }`;result 事件新增 `structuredOutput?`。
 新增 hooks:`onSessionStart` / `onUserPromptSubmit`;`onTurnEnd` 事件新增 `usage?`。
+
+
+### Optional gateway request progress (source candidate)
+
+`QueryOptions.includeRequestProgress?: boolean` defaults to false. When enabled,
+`SDKEvent` additionally includes `{ type: 'request_progress', progress }`, where
+`progress` is the exported `GatewayRequestProgress` type. See the
+[request status guide](./README.md#gateway-request-status-source-candidate) for
+phases, bounded delivery and host lifecycle rules. This nonterminal event must
+not be used as an assistant message, a successful result, or a retry instruction.

package/sdk/README.md

@@ -66,6 +66,43 @@ process events. Those events do not replace or add a terminal result.
 See the [API contract](./API.md) and [recovery guide](../docs/error-recovery-usage.md)
 for consent, external blockers, and continuation rules.
 
+## Gateway request status (source candidate)
+
+Set `includeRequestProgress: true` to receive nonterminal `request_progress`
+events. This is off by default, independent of raw/partial/error diagnostic
+options. It does not change `result`, cancellation, or `onSessionEnd`.
+
+```ts
+for await (const event of query('Summarize this project.', {
+  includeRequestProgress: true,
+})) {
+  if (event.type === 'request_progress') {
+    const { requestId, phase, attempt, elapsedMs, idleMs, slow } = event.progress
+    // Update a transient status indicator, keyed by requestId.
+  }
+  if (event.type === 'result') {
+    // End the turn using the existing success/error contract.
+  }
+}
+```
+
+Phases are `preparing`, `connecting`, `sending`, `waiting_response`,
+`response_headers`, `retry_wait`, `streaming`, and `finished`. `connecting`
+includes pool waiting, DNS, TCP, TLS and proxy negotiation; it does not identify
+which of those substeps is slow. `idleMs` measures time without effective model
+progress. Events contain no prompt, headers, credentials or endpoint URL.
+
+Events are finite (at most 32 per model request), not periodic heartbeats.
+A slow notice never counts as model progress or grants permission to retry.
+`finished` ends a request, not necessarily the turn; clear status on the existing
+result/abort/disconnect path as well. Hosts should keep their own deadlines
+and avoid replaying tools when the remote completion state is unknown.
+
+CLI users can opt in with `--print --output-format stream-json
+--include-request-progress`; each wire event is `system/request_progress`.
+The flag is invalid with text or JSON output. See
+[request deadlines](../docs/gateway-quickstart.md#request-deadlines-and-slow-waits).
+
 ## Architecture
 
 The SDK is the **host side** of the stream-json control protocol that
@@ -146,3 +183,67 @@ provider mapping, skills-dir wrapping, hooks, usage accumulation, file-store
 round-trip. The issue's live end-to-end DoD slice (real model + mock outbound
 endpoint + real process exit) is CoS-side per the issue's division of labor —
 the SDK-side seams it needs are all covered above.
+# Minimal mode and explicit tools
+
+When passing `--bare` through `extraArgs`, the built-in tool set is Bash, Read,
+and Edit (REPL/coordinator modes have their own subset). `--tools default` uses
+that mode's available set; an explicit incompatible selection such as
+`--bare --tools Write` fails with a diagnostic before a model request. Remove
+`--bare` and unset `CLAUDE_CODE_SIMPLE` to request Write. Allow/deny permissions
+still apply; `--allowedTools` does not add tools to the available set.
+
+Use `extraArgs: ['--thinking', 'disabled']` to explicitly disable thinking on
+Anthropic Messages compatible routes. Omitting the option retains the route's
+default. The selection persists across requests; a query handle's
+`setMaxThinkingTokens(0)` explicitly disables it, and `null` restores the default.
+# Persistent sessions and streamed input
+
+`query({ prompt: asyncIterable, options })` accepts `SDKUserMessage` values. It
+submits one message at a time, waits for its result before pulling the next,
+and adds the input UUID as `result.turnId` (generating a UUID if omitted).
+Input EOF closes a streamed query. Invalid messages or producer failures reject
+the event iterator. Consume events as they arrive: an unread streamed query fails
+explicitly at 1024 buffered events instead of retaining unlimited output.
+
+Use `createSession` when the host owns a longer conversation:
+
+```ts
+import { createSession } from '@margay/ccl-core/sdk'
+
+const session = createSession({ cwd: projectDir, maxPendingTurns: 32 })
+try {
+  const first = session.prompt('Inspect the project and describe the failing test.')
+  console.log(await first.result)
+  const next = session.followUp('Fix that failure and run the relevant test.')
+  console.log(await next.result)
+  await session.endInput()
+  // The same child and controls remain alive until close().
+  console.log(session.pid, await session.controls.initializationResult())
+} finally {
+  await session.close()
+}
+```
+
+`prompt` and `followUp` enqueue FIFO; exceeding `maxPendingTurns` throws before
+acceptance. Each `Turn` has a stable `id`, a `result` promise and `cancel()`.
+Cancelling a queued turn rejects its promise. Cancelling an active turn interrupts
+the CLI and returns its interrupted result; already executed tool effects remain.
+`steer(text)` interrupts the active turn and puts the correction ahead of waiting
+follow-ups. It does not undo earlier effects. `endInput()` rejects new inputs and
+waits for accepted turns while preserving controls; `close()` terminates the child
+and rejects unfinished turns. `onEvent` observes events without retaining history.
+
+Permission callbacks can wait for a host decision while the process stays alive.
+Interrupt and close cancel that wait. Returning `{ behavior: 'pending' }` retains
+the existing durable suspend contract: it ends this process and requires
+`resumeWithDecision(sessionId, decision)`; it does not imply automatic approval.
+Uncooperative application iterators/callbacks cannot be forcibly stopped, but do
+not prevent CLI cleanup. One-shot string queries and post-result `rewindFiles`
+retain their existing behavior.
+
+`onLifecycle` observes queue acceptance, actual input dispatch, cancellation requests,
+permission waits, terminal turn outcomes and session closure without another model
+call. `SessionLifecycleEvent` is exported alongside `SDKEvent`. Use `turnId` and
+`origin` to keep background work separate from a waiting user input. Execution
+outcomes do not certify artifacts. See the [runnable terminal host](../examples/assistant/README.md)
+for persistence, explicit permission resumption and no-replay recovery.