@shinaps/skills 0.36.1 → 0.38.0

package/dist/lib/managed-session.js

@@ -0,0 +1,274 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdir, readdir, rename, rm, stat } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { readJson, readJsonIfExists, writeFileAtomic } from './fs.js';
+import { withLock } from './lock.js';
+import { filesBeta, managedBeta } from './managed-ant.js';
+export const staffings = ['LITE', 'BASIC', 'ULTRA'];
+export const permissions = ['commit', 'push', 'draft_pr'];
+const leadKey = './agents/shinaps-dev-managed-cc.md';
+const environmentKey = './environments/shinaps-dev.yaml';
+const permissionLabels = {
+    commit: 'commit',
+    push: 'headへのpush',
+    draft_pr: 'draft PRの作成',
+};
+const sha256 = (text) => createHash('sha256').update(text).digest('hex');
+/**
+ * `--transform id -r` の出力から ID を取り出す。ant は transform のパスが応答に無いと応答の全体を
+ * 出すので、ID の形でない出力を ID として記録しない。
+ */
+async function readId(output, command) {
+    const id = (await output).trim();
+    if (!/^[A-Za-z0-9_]+$/.test(id))
+        throw new Error(`${command} returned no ID.`);
+    return id;
+}
+/**
+ * 依頼を lead へ送るセッションを作る。同じ入力の依頼は同じセッションを返し、作り直さない。
+ * 作成の途中で止まった記録があれば、重複を避けるために作らずに止める。
+ * @param githubToken マウントするリポジトリの token。本文 (stdin) だけで渡す。
+ * @param claudeMdPath `request.claude_md` の元のファイル。upload に使う。
+ */
+export async function runSession(account, request, options) {
+    const { ant, log } = options;
+    return withLock(account.dir, async () => {
+        const { task, claude_md, ...rest } = request;
+        const recorded = {
+            ...rest,
+            task_sha256: sha256(task),
+            claude_md_sha256: claude_md === null ? null : sha256(claude_md),
+        };
+        const requestId = sha256(JSON.stringify(recorded)).slice(0, 32);
+        const recordPath = join(account.dir, 'sessions', `${requestId}.json`);
+        const previous = await readJsonIfExists(recordPath);
+        if (previous?.session_id) {
+            log(`Session already exists for this request: ${previous.session_id}`);
+            return previous.session_id;
+        }
+        if (previous) {
+            throw new Error(`A previous run of this request stopped while creating a session. Check the sessions of account ${account.name} for metadata shinaps_request=${requestId}; delete ${recordPath} only after confirming none was created, then retry.`);
+        }
+        const lock = await readJsonIfExists(join(account.dir, 'definitions', 'claude-lock.json'));
+        const agent = lock?.resources?.[leadKey]?.id;
+        const environment = lock?.resources?.[environmentKey]?.id;
+        if (!agent || !environment) {
+            throw new Error(`Account ${account.name} has no applied lead and environment. Run managed setup --apply first.`);
+        }
+        await mkdir(join(account.dir, 'sessions'), { recursive: true });
+        const record = {
+            request_id: requestId,
+            session_id: null,
+            created_at: options.now().toISOString(),
+            request: recorded,
+        };
+        // 作成より前に記録する。作成後に記録できずに終わっても、次の実行は止まり、重複して作らない。
+        await writeFileAtomic(recordPath, JSON.stringify(record, null, 2) + '\n');
+        const resources = [
+            {
+                type: 'github_repository',
+                url: request.repository.url,
+                mount_path: request.repository.mount_path,
+                ...(options.githubToken ? { authorization_token: options.githubToken } : {}),
+                checkout: { type: 'commit', sha: request.base_sha },
+            },
+        ];
+        if (options.claudeMdPath) {
+            // upload は記録の後に行う。記録の前だと、途中で止まった実行の再実行のたびに Files が増える。
+            let fileId;
+            try {
+                fileId = await readId(ant({
+                    // セッションの Files と同じ beta の Files API に上げる。パスは絶対パスにする (ant は `-` を
+                    // stdin と解釈する)。
+                    argv: [
+                        'beta:files',
+                        'upload',
+                        '--file',
+                        resolve(options.claudeMdPath),
+                        ...filesBeta,
+                        '--transform',
+                        'id',
+                        '-r',
+                    ],
+                    apiKey: account.apiKey,
+                }), 'ant files upload');
+            }
+            catch (error) {
+                // セッションはまだ作っていないので、記録を残すと同じ依頼の再実行が不要に止まる。
+                await rm(recordPath, { force: true });
+                throw error;
+            }
+            resources.push({ type: 'file', file_id: fileId, mount_path: '/CLAUDE.md' });
+        }
+        const body = {
+            agent,
+            environment_id: environment,
+            ...(request.vault_id ? { vault_ids: [request.vault_id] } : {}),
+            title: request.title ?? request.head,
+            metadata: { shinaps_request: requestId, head: request.head, staffing: request.staffing },
+            budget: {
+                type: 'limit',
+                max_list_cost: { amount: request.budget_cents, currency: 'USD' },
+            },
+            resources,
+            initial_events: [
+                { type: 'user.message', content: [{ type: 'text', text: initialMessage(request) }] },
+            ],
+        };
+        const sessionId = await readId(ant({
+            argv: ['beta:sessions', 'create', ...managedBeta, '--transform', 'id', '-r'],
+            apiKey: account.apiKey,
+            body,
+        }), 'ant beta:sessions create');
+        await writeFileAtomic(recordPath, JSON.stringify({ ...record, session_id: sessionId }, null, 2) + '\n');
+        log(`Created session ${sessionId} for account ${account.name}.`);
+        return sessionId;
+    });
+}
+// lead の契約 (managed-agents/skills/dev-managed-cc/SKILL.md の初回メッセージ) の必須入力を、
+// すべて明示する。欠けると lead は質問で止まり、それまでの費用が無駄になる。
+function initialMessage(request) {
+    const budget = Number(request.budget_cents) / 100;
+    return [
+        `リポジトリ: ${request.repository.url}（マウント先 ${request.repository.mount_path}）`,
+        `base: ${request.base} @ ${request.base_sha}`,
+        `head: ${request.head}`,
+        `範囲と受入条件:\n${request.task.trimEnd()}`,
+        `体制: ${request.staffing}`,
+        `許可: ${request.allow.length ? request.allow.map((name) => permissionLabels[name]).join('・') : 'なし（commit・push・draft PRの作成はしない）'}`,
+        `予算: ${budget} USD（セッションの上限 ${request.budget_cents} セント）`,
+        `必須検証（任意）: ${request.verify ?? '指定なし。リポジトリの規約に従う'}`,
+        `author（任意）: ${request.author ?? '指定なし'}`,
+        ...(request.claude_md === null ? [] : ['利用者 CLAUDE.md: /mnt/session/uploads/CLAUDE.md']),
+    ].join('\n');
+}
+/**
+ * このアカウントの記録にあるセッションか確かめる。別アカウントのキーや、CLI が作っていない
+ * セッションを観測・操作しないため。
+ */
+async function requireRecordedSession(account, sessionId) {
+    const directory = join(account.dir, 'sessions');
+    const names = await readdir(directory).catch(() => []);
+    for (const name of names.filter((entry) => entry.endsWith('.json'))) {
+        const record = await readJson(join(directory, name));
+        if (record.session_id === sessionId)
+            return;
+    }
+    throw new Error(`Session ${sessionId} was not created by managed run for account ${account.name}.`);
+}
+/** セッションの状態と、lead の最後のメッセージ (1 行目が `状態: 完了|質問|未完了`) を返す。 */
+export async function sessionStatus(account, sessionId, ant) {
+    await requireRecordedSession(account, sessionId);
+    const call = (argv) => ant({ argv, apiKey: account.apiKey });
+    const session = JSON.parse(await call([
+        'beta:sessions',
+        'retrieve',
+        '--session-id',
+        sessionId,
+        ...managedBeta,
+        '--format',
+        'json',
+        '--transform',
+        '{status,usage,budget}',
+    ]));
+    // 最新の agent.message 1 件だけを取る。全イベント (ツールの呼び出しを含む) を取得しないため。
+    const [last] = (await call([
+        'beta:sessions:events',
+        'list',
+        '--session-id',
+        sessionId,
+        ...managedBeta,
+        '--type',
+        'agent.message',
+        '--order',
+        'desc',
+        '--max-items',
+        '1',
+        '--format',
+        'jsonl',
+        '--transform',
+        '{content}',
+    ]))
+        .split('\n')
+        .filter((line) => line.trim())
+        .map((line) => JSON.parse(line));
+    const message = last?.content
+        ?.filter((block) => block.type === 'text')
+        .map((block) => block.text)
+        .join('\n') ?? null;
+    const state = message?.match(/^状態: (完了|質問|未完了)/)?.[1] ?? null;
+    return { session_id: sessionId, ...session, state, message };
+}
+/** 質問への回答を user.message として送る。新しい許可・予算はここでは加えられない (本文だけ)。 */
+export async function replySession(account, sessionId, text, ant) {
+    await requireRecordedSession(account, sessionId);
+    await ant({
+        argv: ['beta:sessions:events', 'send', '--session-id', sessionId, ...managedBeta],
+        apiKey: account.apiKey,
+        body: { events: [{ type: 'user.message', content: [{ type: 'text', text }] }] },
+    });
+}
+/**
+ * セッションの出力ファイルを `sessions/<session_id>/outputs/` へ保存し、保存したパスを返す。
+ * 差分の適用はしない。同名のファイルは最新のものだけを保存する (lead は毎ターン changes.patch を
+ * 全体の差分で置き換えるため)。
+ */
+export async function collectOutputs(account, sessionId, ant) {
+    await requireRecordedSession(account, sessionId);
+    const listed = (await ant({
+        argv: [
+            'beta:files',
+            'list',
+            '--scope-id',
+            sessionId,
+            ...filesBeta,
+            '--format',
+            'jsonl',
+            '--transform',
+            '{id,filename,size_bytes,created_at}',
+        ],
+        apiKey: account.apiKey,
+    }))
+        .split('\n')
+        .filter((line) => line.trim())
+        .map((line) => JSON.parse(line));
+    const latest = new Map();
+    for (const file of listed) {
+        // 名前はクラウドのエージェントが決める。保存先の外へ書かないよう、ファイル名だけのものに限る。
+        // ID は ant の引数に渡すので、フラグとして解釈される形 (`-` で始まる) を受け付けない。
+        if (!/^[^/\\\0]+$/.test(file.filename) ||
+            file.filename === '.' ||
+            file.filename === '..' ||
+            !/^[A-Za-z0-9_]+$/.test(file.id)) {
+            throw new Error(`Refusing to save an output with an unsafe file name (file ${file.id}).`);
+        }
+        const current = latest.get(file.filename);
+        // 時刻は小数秒の桁数が揃うとは限らないので、文字列ではなく時刻として比べる。
+        if (!current || Date.parse(current.created_at) < Date.parse(file.created_at)) {
+            latest.set(file.filename, file);
+        }
+    }
+    const directory = join(account.dir, 'sessions', sessionId, 'outputs');
+    await mkdir(directory, { recursive: true });
+    const saved = [];
+    for (const file of latest.values()) {
+        const path = join(directory, file.filename);
+        const temporary = join(directory, `.${file.filename}.${randomUUID()}.tmp`);
+        try {
+            await ant({
+                argv: ['beta:files', 'download', '--file-id', file.id, ...filesBeta, '--output', temporary],
+                apiKey: account.apiKey,
+            });
+            const { size } = await stat(temporary);
+            if (file.size_bytes !== undefined && size !== file.size_bytes) {
+                throw new Error(`Downloaded ${file.filename} has ${size} bytes, but the Files API lists ${file.size_bytes}.`);
+            }
+            await rename(temporary, path);
+        }
+        finally {
+            await rm(temporary, { force: true });
+        }
+        saved.push(path);
+    }
+    return saved;
+}

package/dist/lib/managed-setup.js

@@ -0,0 +1,167 @@
+import { createHash } from 'node:crypto';
+import { lstat, mkdir, readdir, readFile, rm } from 'node:fs/promises';
+import { dirname, join, relative, sep } from 'node:path';
+import { errorCode, readJsonIfExists, readTextIfExists, writeFileAtomic } from './fs.js';
+import { withLock } from './lock.js';
+import { managedTemplatePath } from './layout.js';
+import { managedBeta } from './managed-ant.js';
+/** 共通定義の 3 ディレクトリ。`definitions/` には、これと `claude-lock.json` 以外を置かない。 */
+const definitionDirs = ['agents', 'environments', 'skills'];
+const lockName = 'claude-lock.json';
+const upToDate = /Everything is up to date\./;
+/**
+ * 1 アカウントへ共通定義を導入・更新する。`apply` が false なら dry-run の計画を表示するだけで、
+ * クラウドを変更しない。`--prune`・`--force` は使わない (リソースを削除・上書きしないため)。
+ * @param source 同梱の共通定義を含むパッケージのルート。
+ * @returns 計画だけを示した (`planned`)、適用した (`applied`)、変更が無かった (`up-to-date`)。
+ */
+export async function setupAccount(account, options) {
+    const { ant, log } = options;
+    const definitions = join(account.dir, 'definitions');
+    // ant は --lock-file が無いと lock を cwd から上へ探す。definitions に lock が無いとき祖先の lock を
+    // 拾うと、別の組織や構成の lock で対応づけてしまうので、definitions 直下の lock を常に指定する
+    // (指定した lock が無ければ ant はそこへ新しく作る。キーは lock のディレクトリ基準で変わらない)。
+    const run = (mode) => ant({
+        argv: ['apply', mode, '--lock-file', lockName, '.'],
+        apiKey: account.apiKey,
+        cwd: definitions,
+    });
+    return withLock(account.dir, async () => {
+        await syncDefinitions(definitions, join(options.source, managedTemplatePath), join(account.dir, 'definitions.json'));
+        if ((await readTextIfExists(join(definitions, lockName))) === null) {
+            await refuseDuplicates(account, definitions, ant);
+        }
+        const plan = await run('--dry-run');
+        log(plan.trimEnd());
+        // dry-run は適用不能な計画でも終了コード 0 で返るので、計画の文言で判定する。
+        if (/This plan cannot be applied/.test(plan)) {
+            throw new Error(`The plan for account ${account.name} cannot be applied. See the plan above.`);
+        }
+        if (upToDate.test(plan))
+            return 'up-to-date';
+        if (!options.apply)
+            return 'planned';
+        log((await run('--yes')).trimEnd());
+        if (!upToDate.test(await run('--dry-run'))) {
+            throw new Error(`Account ${account.name} still has pending changes after apply. Run setup again without --apply to see them.`);
+        }
+        return 'applied';
+    });
+}
+/**
+ * definitions の3ディレクトリを同梱の定義に揃える。書き換え・削除するのは、setup が最後に書いた
+ * 内容 (`definitions.json` の記録) か今回書く内容と一致するファイルだけ。利用者の編集・追加や、
+ * 記録の無い既存ファイル (旧版の定義ごと複写した場合など) があれば、何も変えずに止める。apply は
+ * ディレクトリ内の定義をすべて送るので、利用者の変更を黙って送ることも失うこともしないため。
+ * definitions には同梱の定義だけを置く。利用者の変更は取り込まず、止めて退避してもらう。
+ * 途中で止まった同期は、各ファイルが記録か今回のどちらかに一致するので、再実行で続きから揃う。
+ * @param record 最後に書いたファイルの相対パス → sha256。apply が送らないよう definitions の外に置く。
+ */
+async function syncDefinitions(definitions, template, record) {
+    await mkdir(definitions, { recursive: true });
+    const unexpected = (await readdir(definitions)).filter((name) => name !== lockName && !definitionDirs.includes(name));
+    const current = await hashTree(definitions, unexpected);
+    const next = await hashTree(template, []);
+    const written = (await readJsonIfExists(record)) ?? {};
+    // 無いファイルは変更にしない。同梱の定義を書き直すだけで利用者の内容は失われず、停止して退避を
+    // 求めると、退避した後の再実行も同じ理由で止まり続けるため。
+    const changed = Object.keys(current)
+        .filter((path) => current[path] !== written[path] && current[path] !== next[path])
+        .sort();
+    if (changed.length) {
+        throw new Error(`Files in ${definitions} differ from what setup wrote: ${changed.join(', ')}. Setup does not overwrite, delete or apply them; it applies only the bundled definitions. Move them out of ${definitions} (keep ${lockName}), then retry and review the plan: it reverts cloud resources that were changed to match the bundled definitions.`);
+    }
+    for (const [path, hash] of Object.entries(next)) {
+        if (current[path] === hash)
+            continue;
+        await mkdir(dirname(join(definitions, path)), { recursive: true });
+        await writeFileAtomic(join(definitions, path), await readFile(join(template, path), 'utf8'));
+    }
+    for (const path of Object.keys(current).filter((path) => !(path in next))) {
+        await rm(join(definitions, path));
+    }
+    await removeEmptyDirectories(definitions);
+    await writeFileAtomic(record, JSON.stringify(next, null, 2) + '\n');
+}
+/**
+ * 3ディレクトリ配下の通常ファイルの相対パス → sha256。通常ファイル以外 (シンボリックリンクなど) と
+ * `extra` の項目は、内容を比べられない変更として値を空にする (記録・同梱のどちらとも一致しない)。
+ */
+async function hashTree(root, extra) {
+    const result = Object.fromEntries(extra.map((name) => [name, '']));
+    for (const directory of definitionDirs) {
+        const kind = await lstat(join(root, directory)).catch((error) => {
+            if (errorCode(error) === 'ENOENT')
+                return null;
+            throw error;
+        });
+        if (!kind)
+            continue;
+        // 3ディレクトリ自体がシンボリックリンクなどなら、辿るとリンク先へ書き込むので変更として止める。
+        if (!kind.isDirectory()) {
+            result[directory] = '';
+            continue;
+        }
+        const entries = await readdir(join(root, directory), { recursive: true, withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.isDirectory())
+                continue;
+            const path = relative(root, join(entry.parentPath, entry.name)).split(sep).join('/');
+            result[path] = entry.isFile()
+                ? createHash('sha256')
+                    .update(await readFile(join(root, path)))
+                    .digest('hex')
+                : '';
+        }
+    }
+    return result;
+}
+// 定義を消した後に残る空のディレクトリを消す。中身の無い skill のディレクトリを apply に渡さないため。
+async function removeEmptyDirectories(definitions) {
+    for (const directory of definitionDirs) {
+        const root = join(definitions, directory);
+        const nested = (await readdir(root, { recursive: true, withFileTypes: true }))
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => join(entry.parentPath, entry.name))
+            .sort((a, b) => b.length - a.length);
+        for (const path of nested) {
+            if ((await readdir(path)).length === 0)
+                await rm(path, { recursive: true });
+        }
+    }
+}
+// lock が無いと apply は既存のリソースと対応づかず、同じ名前で新しく作る。lock の hash は既存の
+// リソースから作り直せないので、同名のリソースがあれば作らずに止め、lock を戻してもらう。
+async function refuseDuplicates(account, definitions, ant) {
+    const names = new Set();
+    for (const directory of ['agents', 'environments']) {
+        for (const file of await readdir(join(definitions, directory))) {
+            const name = (await readFile(join(definitions, directory, file), 'utf8')).match(/^name: (.+)$/m)?.[1];
+            if (name)
+                names.add(name.trim());
+        }
+    }
+    const existing = [];
+    for (const resource of ['beta:agents', 'beta:environments']) {
+        const output = await ant({
+            argv: [
+                resource,
+                'list',
+                ...managedBeta,
+                '--format',
+                'jsonl',
+                '--transform',
+                '{name,archived_at}',
+            ],
+            apiKey: account.apiKey,
+        });
+        for (const line of output.split('\n').filter((text) => text.trim())) {
+            const item = JSON.parse(line);
+            if (item.name && names.has(item.name) && !item.archived_at)
+                existing.push(item.name);
+        }
+    }
+    if (existing.length) {
+        throw new Error(`Account ${account.name} has no lock, but resources with the same names exist: ${[...new Set(existing)].join(', ')}. Applying would create duplicates. If you used Managed Agents before, move the previous claude-lock.json (for example <definitions>/claude-lock.json from .shinaps/managed.json version 1) to ${definitions}/, then retry.`);
+    }
+}