UNCUT দিয়ে শেল পাইপলাইনে লসলেস কোডিং এজেন্ট চালান

UNCUT কী?

UNCUT হলো shell pipeline, CI job, container এবং agent পরীক্ষার জন্য তৈরি একটি headless coding-agent harness। এটি একটি ছোট, statically linked Go binary হিসেবে বিতরণ করা হয় এবং standard input ও standard output-এর মাধ্যমে যোগাযোগ করে। এতে কোনো terminal user interface, telemetry, plugin system, background agent, automatic retry বা hidden context compaction নেই।

এর প্রধান বৈশিষ্ট্য হলো lossless transport contract। UNCUT প্রতিটি model call-এ সম্পূর্ণ conversation পাঠায় এবং বৈধ UTF-8 prompt, সংরক্ষিত message, file content বা command output truncate, summarize, prune বা rewrite করে না। কোনো provider output limit-এর কারণে response বন্ধ করলে UNCUT সেটিকে সফল উত্তর হিসেবে গণ্য না করে error জানায়।

গুরুত্বপূর্ণ: Lossless transport কোনো model-এর context window বাড়ায় না এবং provider-side processing নিয়ন্ত্রণ করে না। কোনো provider এখনও অতিরিক্ত বড় request প্রত্যাখ্যান করতে পারে। UNCUT content নীরবে সরিয়ে না দিয়ে সেই ব্যর্থতাটি দৃশ্যমান করে।

মূল বৈশিষ্ট্য

• সম্পূর্ণ context: প্রতিটি model request-এ সব সংরক্ষিত message ও tool result পাঠানো হয়।
• Headless operation: চূড়ান্ত text stdout-এ লেখা হয়, আর --json structured NDJSON event সরবরাহ করে।
• বহনযোগ্য binary: amd64 ও arm64 architecture-এ Linux, macOS এবং Windows-এর জন্য release পাওয়া যায়।
• Provider-neutral protocol: UNCUT OpenAI-compatible Chat Completions endpoint, including local server, এর সঙ্গে কাজ করে।
• Resumable session: Append-only JSONL file সম্পূর্ণ message ও tool result সংরক্ষণ করে।
• চারটি নির্দিষ্ট tool: Agent file পড়তে, file লিখতে, exact text প্রতিস্থাপন করতে এবং command চালাতে পারে।
• স্পষ্ট failure: Invalid UTF-8, malformed session, output truncation এবং step-limit exhaustion নীরব recovery-এর বদলে error তৈরি করে।

UNCUT ইনস্টল করুন

Linux

আপনার architecture-এর সঙ্গে মেলে এমন release binary download করুন। ARM64 system-এ amd64-এর পরিবর্তে arm64 ব্যবহার করুন।

VERSION=0.1.1
ARCH=amd64
curl -fSLo uncut "https://github.com/Balanov/uncut/releases/download/v${VERSION}/uncut-linux-${ARCH}"
mkdir -p "$HOME/.local/bin"
install -m 0755 uncut "$HOME/.local/bin/uncut"
export PATH="$HOME/.local/bin:$PATH"
uncut --version

আগে থেকে না থাকলে স্থায়ী PATH configuration-এ $HOME/.local/bin যোগ করুন।

macOS

Apple Silicon system-এ সাধারণত arm64 এবং Intel Mac-এ amd64 ব্যবহার হয়।

VERSION=0.1.1
ARCH=arm64
curl -fSLo uncut "https://github.com/Balanov/uncut/releases/download/v${VERSION}/uncut-darwin-${ARCH}"
mkdir -p "$HOME/.local/bin"
install -m 0755 uncut "$HOME/.local/bin/uncut"
export PATH="$HOME/.local/bin:$PATH"
uncut --version

Windows PowerShell

$Version = "0.1.1"
$Arch = "amd64"
$Dest = "$env:LOCALAPPDATA\Programs\UNCUT"
New-Item -ItemType Directory -Force $Dest | Out-Null
Invoke-WebRequest -Uri "https://github.com/Balanov/uncut/releases/download/v$Version/uncut-windows-$Arch.exe" -OutFile "$Dest\uncut.exe"
$env:Path = "$Dest;$env:Path"
uncut --version

Windows ARM64-এ amd64-এর পরিবর্তে arm64 ব্যবহার করুন। ভবিষ্যতের PowerShell session-এ command-টি ব্যবহারের জন্য destination directory-টি user PATH-এ যোগ করুন।

Go দিয়ে ইনস্টল বা build করুন

Go 1.26 বা পরবর্তী সংস্করণ ইনস্টল করা থাকলে সরাসরি latest version ইনস্টল করুন:

go install github.com/Balanov/uncut/cmd/uncut@latest

অন্যথায় repository checkout build করুন:

git clone https://github.com/Balanov/uncut.git
cd uncut
go build -trimpath -ldflags="-s -w" -o bin/uncut ./cmd/uncut

Windows-এ output path হিসেবে bin/uncut.exe ব্যবহার করুন।

Download করা binary যাচাই করুন

প্রতিটি release-এর সঙ্গে একটি checksums.txt file থাকে। নিচের উদাহরণটি Linux amd64 download যাচাই করে:

VERSION=0.1.1
ARCH=amd64
curl -fSLO "https://github.com/Balanov/uncut/releases/download/v${VERSION}/checksums.txt"
grep "uncut-linux-${ARCH}$" checksums.txt | sha256sum -c -

Release binary-গুলো বর্তমানে code-signed নয়, তাই Gatekeeper বা SmartScreen warning দেখাতে পারে। Executable অনুমোদনের আগে SHA-256 checksum যাচাই করুন। macOS-এ যাচাই করার পর শুধুমাত্র ইনস্টল করা binary থেকে quarantine সরানো যায়:

xattr -d com.apple.quarantine "$HOME/.local/bin/uncut"

একটি model provider configure করুন

UNCUT-এর একটি model identifier প্রয়োজন। Hosted service-এর জন্য সাধারণত API key-ও দরকার হয়। দুটি value সেট করে prompt চালান:

export UNCUT_API_KEY="your-api-key"
export UNCUT_MODEL="your-model-id"
uncut "Inspect this repository and fix the failing tests"

UNCUT_BASE_URL বা OPENAI_BASE_URL সেট না থাকলে default endpoint হলো https://api.openai.com/v1। অন্য কোনো OpenAI-compatible endpoint ব্যবহার করতে তার base URL দিন:

export UNCUT_BASE_URL="https://openrouter.ai/api/v1"

UNCUT UNCUT_API_KEY না পেলে OPENAI_API_KEY ব্যবহার করে। Local endpoint-এর জন্য defaultভাবে key প্রয়োজন হয় না।

Local Ollama-তে সংযোগ করুন

README-তে পরীক্ষিত উদাহরণে ইনস্টল করা, tool-capable qwen3:8b model ব্যবহার করা হয়েছে:

ollama pull qwen3:8b
export UNCUT_BASE_URL="http://localhost:11434/v1"
export UNCUT_MODEL="qwen3:8b"
uncut "Explain this repository"

উদাহরণটির পরিবর্তে আপনার machine-এ ইনস্টল করা model ব্যবহার করুন। Tool-call-এর quality ও behavior নির্বাচিত model-এর ওপর নির্ভর করে।

আপনার প্রথম coding task চালান

এজেন্ট যে রিপোজিটরি পরিদর্শন করবে, সেখান থেকে UNCUT শুরু করুন। ডিফল্টভাবে, বর্তমান ডিরেক্টরি ফাইল টুল ও শেল কমান্ডের জন্য ওয়ার্কস্পেস হয়ে যায়।

cd path/to/project
uncut "Inspect this repository, run the tests, and fix the failure"

কাজ চলাকালে মডেল চারটি টুল কল করতে পারে:

• read_file একটি সম্পূর্ণ UTF-8 টেক্সট ফাইল পড়ে।
• write_file সম্পূর্ণ কনটেন্ট লিখে এবং অনুপস্থিত প্যারেন্ট ডিরেক্টরি তৈরি করে।
• replace ঠিক একটি occurrence প্রতিস্থাপন করে। শূন্য বা একাধিক ম্যাচ পেলে এটি ব্যর্থ হয়।
• run_command exit code এবং stdout ও stderr-এর সম্পূর্ণ সম্মিলিত আউটপুট ফেরত দেয়।

ফাইল-টুলের পাথ অবশ্যই ওয়ার্কস্পেসের ভেতরে থাকতে হবে। Unix-এ কমান্ড /bin/sh -c-এর মাধ্যমে চলে। Windows-এ এগুলো cmd.exe /D /S /C-এর মাধ্যমে চলে।

Unix পাইপলাইনে UNCUT ব্যবহার করুন

UNCUT পাইপ করা ইনপুট হুবহু প্রম্পটের শেষে যুক্ত করে। তাই অস্থায়ী ফাইল তৈরি না করেই রিভিউ ও লগ বিশ্লেষণের জন্য এটি উপযোগী।

git diff | uncut "Review this diff. Do not edit files."
cat failing-test.log | uncut "Find the likely cause"

ইনপুট অবশ্যই বৈধ UTF-8 হতে হবে। UNCUT অবৈধ ইনপুট নীরবে প্রতিস্থাপন না করে প্রত্যাখ্যান করে। এটি বাইনারি ফাইলও প্রত্যাখ্যান করে। Windows-এ সম্ভব হলে ইউটিলিটিগুলোকে UTF-8 আউটপুট দেওয়ার জন্য কনফিগার করুন, কারণ কিছু কমান্ড UTF-16 বা code-page আউটপুট তৈরি করে।

স্ট্রাকচার্ড NDJSON ইভেন্ট গ্রহণ করুন

স্ক্রিপ্ট, CI সিস্টেম বা অন্যান্য এজেন্ট অবকাঠামোর সঙ্গে UNCUT সংযুক্ত করার সময় --json ব্যবহার করুন:

uncut --json "Run the tests and fix the failure"

ইভেন্ট স্ট্রিমে নিম্নলিখিত রেকর্ডের ধরন থাকতে পারে:

• user ব্যবহারকারীর বার্তার জন্য।
• assistant সহকারীর বার্তা এবং সম্পূর্ণ টুল কলের জন্য।
• assistant_meta ব্যবহারসংক্রান্ত তথ্য ও সমাপ্তির কারণের জন্য।
• tool সম্পূর্ণ টুল ফলাফলের জন্য।
• done রান সফলভাবে সম্পন্ন হলে।
• error রান ব্যর্থ হলে।

UNCUT নন-স্ট্রিমিং Chat Completions ব্যবহার করে। এটি টেক্সট ও টুল কল সমর্থন করে, তবে ইমেজ ইনপুট সমর্থন করে না।

সেশন তৈরি ও পুনরায় চালু করুন

একটি সেশন হলো সম্পূর্ণ কথোপকথন ও টুল ফলাফল ধারণকারী append-only JSONL রেকর্ড। সেশন ফাইল দিয়ে একটি কাজ শুরু করুন, তারপর চালিয়ে যেতে একই ফাইল পুনরায় ব্যবহার করুন:

uncut --session .uncut/work.jsonl "Start the refactor"
uncut --session .uncut/work.jsonl "Continue with the tests"

ফাইলটি আগে থেকেই থাকলে UNCUT তার সম্পূর্ণ ইতিহাস লোড করে। প্রতিটি ধাপের পর নতুন রেকর্ড যুক্ত ও সিঙ্ক্রোনাইজ করা হয়। অবৈধ বা অসম্পূর্ণ রেকর্ড স্পষ্ট ত্রুটি সৃষ্টি করে এবং সেশন লোড করানোর জন্য সেগুলো বাদ দেওয়া হয় না।

সেশন ফাইলে সোর্স কোড, কমান্ড আউটপুট, শংসাপত্র বা অন্যান্য গোপন তথ্য থাকতে পারে। এগুলো যথাযথভাবে সুরক্ষিত রাখুন এবং version control-এ commit করা এড়িয়ে চলুন।

ওয়ার্কস্পেস ও এজেন্ট লুপ নিয়ন্ত্রণ করুন

বর্তমান ডিরেক্টরি ছাড়া অন্য কোনো ওয়ার্কস্পেসে চালাতে --cwd ব্যবহার করুন:

uncut --cwd ./services/api "Run the API tests and explain any failures"

বেশ কয়েকটি flag অনুরোধ ও লুপের আচরণ নিয়ন্ত্রণ করে:

• --max-steps <n> মডেল কলের সংখ্যা সীমিত করে। ডিফল্ট হলো 32।
• --max-tokens <n> provider-এর ডিফল্টের পরিবর্তে একটি নির্দিষ্ট output limit নির্ধারণ করে।
• --request-timeout <duration> প্রতি অনুরোধের timeout তার ডিফল্ট 10m থেকে পরিবর্তন করে। 0 দিলে timeout নিষ্ক্রিয় হয়।
• --no-agents UNCUT-কে ওয়ার্কস্পেসের AGENTS.md পড়তে বাধা দেয়।

ডিফল্টভাবে, UNCUT ওয়ার্কস্পেসের root থেকে AGENTS.md-এর সম্পূর্ণ কনটেন্ট পড়ে system prompt-এ যুক্ত করে। কোনো সেশন পুনরায় চালু করার সময় এটি বর্তমান ফাইল থেকে system message পুনর্নির্মাণ না করে আগে সংরক্ষিত মূল system message পুনরায় ব্যবহার করে।

Exit code বুঝুন

নির্ভরযোগ্য exit code UNCUT-কে automation-এর জন্য উপযোগী করে:

• 0 বোঝায় এজেন্ট একটি সফল final answer তৈরি করেছে।
• 1 provider, input/output, session বা execution error নির্দেশ করে।
• 2 অবৈধ command-line ব্যবহারের নির্দেশক।
• 3 বোঝায় provider finish_reason=length বা max_tokens ফেরত দিয়েছে; UNCUT অসম্পূর্ণ উত্তর প্রত্যাখ্যান করেছে।
• 4 বোঝায় final answer দেওয়ার আগে সর্বোচ্চ সংখ্যক ধাপে পৌঁছে গেছে।

CI-তে প্রতিটি nonzero code-কে ব্যর্থ রান হিসেবে গণ্য করুন এবং stderr অথবা --json থেকে পাওয়া চূড়ান্ত error ইভেন্ট পরীক্ষা করুন।

উন্নত পরামর্শ

সীমা সচেতনভাবে নির্ধারণ করুন

UNCUT context compact করে না, তাই দীর্ঘ সেশন ও বড় টুল ফলাফল শেষ পর্যন্ত মডেলের context window-এর সীমা ছাড়িয়ে যেতে পারে। উপযুক্ত সময়ে নতুন সেশন শুরু করুন, পর্যাপ্ত context capacity-সম্পন্ন provider বেছে নিন এবং provider-এর response limit বুঝে তবেই --max-tokens নির্ধারণ করুন। UNCUT অসম্পূর্ণ response একত্র করে না বা স্বয়ংক্রিয়ভাবে retry করে না।

স্বয়ংক্রিয় রান machine-readable রাখুন

CI ও integration-এর জন্য conversational final text পার্স না করে --json ব্যবহার করুন। পৃথক metadata event-গুলোর মাধ্যমে assistant content-এর সঙ্গে মেশানো ছাড়াই consumer-রা finish reason ও usage পরীক্ষা করতে পারে।

অবিশ্বস্ত কাজের জন্য বিচ্ছিন্ন পরিবেশ ব্যবহার করুন

UNCUT কোনো sandbox নয়। ফাইল টুলগুলো ওয়ার্কস্পেসের সীমানা প্রয়োগ করলেও run_command বর্তমান operating-system user-এর permission নিয়ে চলে এবং ওই file check দ্বারা সীমাবদ্ধ নয়। অবিশ্বস্ত prompt বা repository একটি disposable container অথবা অন্য কোনো বিচ্ছিন্ন পরিবেশে চালান। ফাইল পরিবর্তন ও session record নিজে পর্যালোচনা করুন।

কোনো অনুমোদন ডায়ালগ, স্বয়ংক্রিয় কমিট, স্বয়ংক্রিয় পুনঃচেষ্টা বা গোপন পুনরুদ্ধার লুপ নেই। এতে এক্সিকিউশনের আচরণ সরাসরি থাকে, তবে এর অর্থ হলো উপযুক্তভাবে সীমাবদ্ধ একটি পরিবেশ বেছে নেওয়ার দায়িত্ব আপনার।

স্থানীয়ভাবে lossless চুক্তি যাচাই করুন

রিপোজিটরিতে একটি নির্ধারক প্রুফ স্ক্রিপ্ট রয়েছে, যা প্রকৃত বাইনারি এবং একটি স্থানীয় প্রোভাইডার ব্যবহার করে। এর জন্য Python 3 প্রয়োজন, তবে কোনো API key, বাহ্যিক মডেল বা তৃতীয় পক্ষের Python প্যাকেজের প্রয়োজন নেই:

go build -o bin/uncut ./cmd/uncut
python bench/proof.py ./bin/uncut

প্রুফটি বড় ফাইল ও কমান্ডের আউটপুটের সম্পূর্ণ পরিবহন, সঠিক সেশন পুনরারম্ভ, সম্পাদনার আচরণ, স্পষ্ট truncation ব্যর্থতা, ধাপের সীমা এবং অবৈধ UTF-8 ব্যবহারের আচরণ যাচাই করে। এই পরীক্ষাগুলো মডেলের গুণমান নয়, পরিবহন আচরণ পরিমাপ করে। রেকর্ড করা ফলাফল ও পুনরুৎপাদনের নির্দেশনা UNCUT রিপোজিটরিতে পাওয়া যাবে।

ডেভেলপমেন্ট পরীক্ষা চালান

UNCUT-এ পরিবর্তন করার সময় Go কোড ফরম্যাট, পরীক্ষা এবং vet করুন:

gofmt -w cmd internal
go test -count=1 ./...
go vet ./...

উপসংহার

UNCUT টার্মিনাল, পাইপলাইন, কনটেইনার এবং CI সিস্টেম থেকে কোডিং এজেন্ট চালানোর জন্য ইচ্ছাকৃতভাবে ছোট ও স্বচ্ছ একটি পদ্ধতি প্রদান করে। সম্পূর্ণ-মেসেজ পরিবহন, স্পষ্ট ব্যর্থতা পরিচালনা, পুনরারম্ভযোগ্য সেশন, কাঠামোবদ্ধ ইভেন্ট এবং বিল্ট-ইন চারটি টুল এটিকে এমন পরিস্থিতিতে উপযোগী করে তোলে, যেখানে নীরবে কনটেক্সট কমে যাওয়া গ্রহণযোগ্য নয়। একটি OpenAI-সামঞ্জস্যপূর্ণ এন্ডপয়েন্ট কনফিগার করুন, বিচ্ছিন্ন ওয়ার্কস্পেসে শুরু করুন এবং পুনরুৎপাদনযোগ্য অটোমেশন প্রয়োজন হলে সেশন বা NDJSON আউটপুট ব্যবহার করুন।